summaryrefslogtreecommitdiff
path: root/doc/lispref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/lispref')
-rw-r--r--doc/lispref/backups.texi78
-rw-r--r--doc/lispref/customize.texi20
-rw-r--r--doc/lispref/display.texi33
-rw-r--r--doc/lispref/edebug.texi15
-rw-r--r--doc/lispref/files.texi42
-rw-r--r--doc/lispref/frames.texi28
-rw-r--r--doc/lispref/functions.texi37
-rw-r--r--doc/lispref/help.texi3
-rw-r--r--doc/lispref/internals.texi226
-rw-r--r--doc/lispref/intro.texi4
-rw-r--r--doc/lispref/keymaps.texi7
-rw-r--r--doc/lispref/loading.texi7
-rw-r--r--doc/lispref/minibuf.texi60
-rw-r--r--doc/lispref/modes.texi50
-rw-r--r--doc/lispref/objects.texi8
-rw-r--r--doc/lispref/os.texi17
-rw-r--r--doc/lispref/positions.texi8
-rw-r--r--doc/lispref/processes.texi49
-rw-r--r--doc/lispref/searching.texi11
-rw-r--r--doc/lispref/strings.texi45
-rw-r--r--doc/lispref/text.texi16
-rw-r--r--doc/lispref/tips.texi65
-rw-r--r--doc/lispref/variables.texi7
-rw-r--r--doc/lispref/windows.texi14
24 files changed, 612 insertions, 238 deletions
diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index 4ed1a10fcf6..379279575ca 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -414,10 +414,16 @@ version that the caller should consider deleting now.
@end smallexample
@end defun
-@c Emacs 19 feature
+@defun file-backup-file-names filename
+This function returns a list of all the backup file names for
+@var{filename}, or @code{nil} if there are none. The files are sorted
+by modification time, descending, so that the most recent files are
+first.
+@end defun
+
@defun file-newest-backup filename
-This function returns the name of the most recent backup file for
-@var{filename}, or @code{nil} if that file has no backup files.
+This function returns the first element of the list returned by
+@code{file-backup-file-names}.
Some file comparison commands use this function so that they can
automatically compare a file with its most recent backup.
@@ -460,6 +466,32 @@ Auto Save mode is enabled if @code{buffer-auto-save-file-name} is
non-@code{nil} and @code{buffer-saved-size} (see below) is non-zero.
@end deffn
+@defvar auto-save-file-name-transforms
+This variable lists transforms to apply to buffer's file name before
+making the auto-save file name.
+
+Each transform is a list of the form @w{@code{(@var{regexp}
+@var{replacement} [@var{uniquify}])}}. @var{regexp} is a regular
+expression to match against the file name; if it matches,
+@code{replace-match} is used to replace the matching part with
+@var{replacement}. If the optional element @var{uniquify} is non-nil,
+the auto-save file name is constructed by concatenating the directory
+part of the transformed file name with the buffer's file name in which
+all directory separators were changed to @samp{!} to prevent clashes.
+(This will not work correctly if your filesystem truncates the
+resulting name.)
+
+All the transforms in the list are tried, in the order they are listed.
+When one transform applies, its result is final;
+no further transforms are tried.
+
+The default value is set up to put the auto-save files of remote files
+into the temporary directory (@pxref{Unique File Names}).
+
+On MS-DOS filesystems without long names this variable is always
+ignored.
+@end defvar
+
@defun auto-save-file-name-p filename
This function returns a non-@code{nil} value if @var{filename} is a
string that could be the name of an auto-save file. It assumes
@@ -481,21 +513,6 @@ name. The argument @var{filename} should not contain a directory part.
@result{} nil
@end group
@end example
-
-The standard definition of this function is as follows:
-
-@example
-@group
-(defun auto-save-file-name-p (filename)
- "Return non-nil if FILENAME can be yielded by..."
- (string-match "^#.*#$" filename))
-@end group
-@end example
-
-This function exists so that you can customize it if you wish to
-change the naming convention for auto-save files. If you redefine it,
-be sure to redefine the function @code{make-auto-save-file-name}
-correspondingly.
@end defun
@defun make-auto-save-file-name
@@ -511,31 +528,6 @@ function should check that variable first.
@result{} "/xcssun/users/rms/lewis/#backups.texi#"
@end group
@end example
-
-Here is a simplified version of the standard definition of this
-function:
-
-@example
-@group
-(defun make-auto-save-file-name ()
- "Return file name to use for auto-saves \
-of current buffer.."
- (if buffer-file-name
-@end group
-@group
- (concat
- (file-name-directory buffer-file-name)
- "#"
- (file-name-nondirectory buffer-file-name)
- "#")
- (expand-file-name
- (concat "#%" (buffer-name) "#"))))
-@end group
-@end example
-
-This exists as a separate function so that you can redefine it to
-customize the naming convention for auto-save files. Be sure to
-change @code{auto-save-file-name-p} in a corresponding way.
@end defun
@defopt auto-save-visited-file-name
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 2a72276bc56..85912470795 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -124,6 +124,11 @@ Link to the documentation of a variable; @var{variable} is a string
which specifies the name of the variable to describe with
@code{describe-variable} when the user invokes this link.
+@item (face-link @var{face})
+Link to the documentation of a face; @var{face} is a string which
+specifies the name of the face to describe with @code{describe-face}
+when the user invokes this link.
+
@item (custom-group-link @var{group})
Link to another customization group. Invoking it creates a new
customization buffer for @var{group}.
@@ -358,6 +363,10 @@ This is meaningful only for certain types, currently including
@code{hook}, @code{plist} and @code{alist}. See the definition of the
individual types for a description of how to use @code{:options}.
+Re-evaluating a @code{defcustom} form with a different @code{:options}
+value does not clear the values added by previous evaluations, or
+added by calls to @code{custom-add-frequent-value} (see below).
+
@item :set @var{setfunction}
@kindex set@r{, @code{defcustom} keyword}
Specify @var{setfunction} as the way to change the value of this
@@ -485,6 +494,10 @@ list of reasonable values.
The precise effect of adding a value depends on the customization type
of @var{symbol}.
+
+Since evaluating a @code{defcustom} form does not clear values added
+previously, Lisp programs can use this function to add values for user
+options not yet defined.
@end defun
Internally, @code{defcustom} uses the symbol property
@@ -1189,6 +1202,13 @@ current value is valid for the widget. Otherwise, it should return
the widget containing the invalid data, and set that widget's
@code{:error} property to a string explaining the error.
+@item :type-error @var{string}
+@kindex type-error@r{, customization keyword}
+@var{string} should be a string that describes why a value doesn't
+match the type, as determined by the @code{:match} function. When the
+@code{:match} function returns @code{nil}, the widget's @code{:error}
+property will be set to @var{string}.
+
@ignore
@item :indent @var{columns}
Indent this item by @var{columns} columns. The indentation is used for
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index be2de000c35..7d1c14c8169 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1318,12 +1318,6 @@ the buffer specified by @var{buffer-or-name} current for running
@var{body}.
@end defmac
-@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body
-This macro is like @code{with-current-buffer-window} but unlike that
-displays the buffer specified by @var{buffer-or-name} @emph{before}
-running @var{body}.
-@end defmac
-
A window showing a temporary buffer can be fitted to the size of that
buffer using the following mode:
@@ -2462,12 +2456,15 @@ Draw a box with lines of width 1, in the foreground color.
@item @var{color}
Draw a box with lines of width 1, in color @var{color}.
-@item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
-This way you can explicitly specify all aspects of the box. The value
-@var{width} specifies the width of the lines to draw; it defaults to
-1. A negative width @minus{}@var{n} means to draw a line of width @var{n}
-whose top and bottom parts occupy the space of the underlying text,
-thus avoiding any increase in the character height.
+@item @code{(:line-width (@var{vwidth} . @var{hwidth}) :color @var{color} :style @var{style})}
+This way you can explicitly specify all aspects of the box. The values
+@var{vwidth} and @var{hwidth} specifies respectively the width of the
+vertical and horizontal lines to draw; they default to (1 . 1).
+A negative horizontal or vertical width @minus{}@var{n} means to draw a line
+of width @var{n} that occupies the space of the underlying text, thus
+avoiding any increase in the character height or width. For simplification
+the width could be specified with only a single number @var{n} instead
+of a list, such case is equivalent to @code{((abs @var{n}) . @var{n})}.
The value @var{color} specifies the color to draw with. The default is
the foreground color of the face for simple boxes, and the background
@@ -5578,6 +5575,15 @@ 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}.
@@ -6923,6 +6929,9 @@ such as @code{forward-button} and @code{backward-button} are
additionally available in the keymap stored in
@code{button-buffer-map}; a mode which uses buttons may want to use
@code{button-buffer-map} as a parent keymap for its keymap.
+Alternatively, the @code{button-mode} can be switched on for much the
+same effect: It's a minor mode that does nothing else than install
+@code{button-buffer-map} as a minor mode keymap.
If the button has a non-@code{nil} @code{follow-link} property, and
@code{mouse-1-click-follows-link} is set, a quick @key{mouse-1} click
diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index b5b5ea0a645..6404e068dae 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -1362,6 +1362,11 @@ while matching the remainder of the specifications at this level. This
is primarily used to generate more specific syntax error messages. See
@ref{Backtracking}, for more details. Also see the @code{let} example.
+@item &error
+@code{&error} should be followed by a string, an error message, in the
+edebug-spec; it aborts the instrumentation, displaying the message in
+the minibuffer.
+
@item @var{other-symbol}
@cindex indirect specifications
Any other symbol in a specification list may be a predicate or an
@@ -1433,6 +1438,16 @@ name component for the definition. You can use this to add a unique,
static component to the name of the definition. It may be used more
than once.
+@item :unique
+This construct is like @code{:name}, but generates unique names. It
+does not match an argument. The element following @code{:unique}
+should be a string; it is used as the prefix for an additional name
+component for the definition. You can use this to add a unique,
+dynamic component to the name of the definition. This is useful for
+macros that can define the same symbol multiple times in different
+scopes, such as @code{cl-flet}; @ref{Function Bindings,,,cl}. It may
+be used more than once.
+
@item arg
The argument, a symbol, is the name of an argument of the defining form.
However, lambda-list keywords (symbols starting with @samp{&})
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 6ca2834fbd4..92cbc2a1c91 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -928,7 +928,7 @@ also checks that the file's group would be unchanged.
This function does not follow symbolic links.
@end defun
-@defun file-modes filename
+@defun file-modes filename &optional flag
@cindex mode bits
@cindex file permissions
@cindex permissions, file
@@ -946,12 +946,19 @@ The highest possible value is 4095 (7777 octal), meaning that everyone
has read, write, and execute permission, the @acronym{SUID} bit is set
for both others and group, and the sticky bit is set.
+By default this function follows symbolic links. However, if the
+optional argument @var{flag} is the symbol @code{nofollow}, this
+function does not follow @var{filename} if it is a symbolic link;
+this can help prevent inadvertently obtaining the mode bits of a file
+somewhere else, and is more consistent with @code{file-attributes}
+(@pxref{File Attributes}).
+
@xref{Changing Files}, for the @code{set-file-modes} function, which
can be used to set these permissions.
@example
@group
-(file-modes "~/junk/diffs")
+(file-modes "~/junk/diffs" 'nofollow)
@result{} 492 ; @r{Decimal integer.}
@end group
@group
@@ -960,7 +967,7 @@ can be used to set these permissions.
@end group
@group
-(set-file-modes "~/junk/diffs" #o666)
+(set-file-modes "~/junk/diffs" #o666 'nofollow)
@result{} nil
@end group
@@ -1801,9 +1808,17 @@ See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@cindex file permissions, setting
@cindex permissions, file
@cindex file modes, setting
-@deffn Command set-file-modes filename mode
+@deffn Command set-file-modes filename mode &optional flag
This function sets the @dfn{file mode} (or @dfn{permissions}) of
-@var{filename} to @var{mode}. This function follows symbolic links.
+@var{filename} to @var{mode}.
+
+By default this function follows symbolic links. However, if the
+optional argument @var{flag} is the symbol @code{nofollow}, this
+function does not follow @var{filename} if it is a symbolic link;
+this can help prevent inadvertently changing the mode bits of a file
+somewhere else. On platforms that do not support changing mode bits
+on a symbolic link, this function signals an error when @var{filename}
+is a symbolic link and @var{flag} is @code{nofollow}.
If called non-interactively, @var{mode} must be an integer. Only the
lowest 12 bits of the integer are used; on most systems, only the
@@ -1811,7 +1826,7 @@ lowest 9 bits are meaningful. You can use the Lisp construct for
octal numbers to enter @var{mode}. For example,
@example
-(set-file-modes #o644)
+(set-file-modes "myfile" #o644 'nofollow)
@end example
@noindent
@@ -1894,11 +1909,24 @@ omitted or @code{nil}, it defaults to 0, i.e., no access rights at
all.
@end defun
-@defun set-file-times filename &optional time
+@defun file-modes-number-to-symbolic modes
+This function converts a numeric file mode specification in
+@var{modes} into the equivalent symbolic form.
+@end defun
+
+@defun set-file-times filename &optional time flag
This function sets the access and modification times of @var{filename}
to @var{time}. The return value is @code{t} if the times are successfully
set, otherwise it is @code{nil}. @var{time} defaults to the current
time and must be a time value (@pxref{Time of Day}).
+
+By default this function follows symbolic links. However, if the
+optional argument @var{flag} is the symbol @code{nofollow}, this
+function does not follow @var{filename} if it is a symbolic link;
+this can help prevent inadvertently changing the times of a file
+somewhere else. On platforms that do not support changing times
+on a symbolic link, this function signals an error when @var{filename}
+is a symbolic link and @var{flag} is @code{nofollow}.
@end defun
@defun set-file-extended-attributes filename attribute-alist
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index ae61b269520..22d32c00d9b 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -2193,10 +2193,11 @@ it and see if it works.)
@vindex ns-appearance@r{, a frame parameter}
@item ns-appearance
Only available on macOS, if set to @code{dark} draw this frame's
-window-system window using the ``vibrant dark'' theme, otherwise use
-the system default. The ``vibrant dark'' theme can be used to set the
-toolbar and scrollbars to a dark appearance when using an Emacs theme
-with a dark background.
+window-system window using the ``vibrant dark'' theme, and if set to
+@code{light} use the ``aqua'' theme, otherwise use the system default.
+The ``vibrant dark'' theme can be used to set the toolbar and
+scrollbars to a dark appearance when using an Emacs theme with a dark
+background.
@vindex ns-transparent-titlebar@r{, a frame parameter}
@item ns-transparent-titlebar
@@ -2220,6 +2221,9 @@ How to display the cursor. Legitimate values are:
@table @code
@item box
Display a filled box. (This is the default.)
+@item (box . @var{size})
+Display a filled box. However, display it as a hollow box if point is
+under masked image larger than @var{size} pixels in either dimension.
@item hollow
Display a hollow box.
@item nil
@@ -3872,13 +3876,15 @@ 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 and if @code{browse-url-browser-function} is
-an alist, Emacs looks for a match there. If no match is found the
-text for the URL is inserted. If you want to alter Emacs behavior,
-you can customize these variables.
+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.
@node Color Names
@section Color Names
@@ -3970,11 +3976,11 @@ If @var{color} is not defined, the value is @code{nil}.
(color-values "black")
@result{} (0 0 0)
(color-values "white")
- @result{} (65280 65280 65280)
+ @result{} (65535 65535 65535)
(color-values "red")
- @result{} (65280 0 0)
+ @result{} (65535 0 0)
(color-values "pink")
- @result{} (65280 49152 51968)
+ @result{} (65535 49344 52171)
(color-values "hungry")
@result{} nil
@end example
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 2898cb4d2b4..e8e22078d9b 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -762,6 +762,11 @@ arguments, rather than a single list. We say that @code{apply}
@dfn{spreads} this list so that each individual element becomes an
argument.
+@code{apply} with a single argument is special: the first element of
+the argument, which must be a non-empty list, is called as a function
+with the remaining elements as individual arguments. Passing two or
+more arguments will be faster.
+
@code{apply} returns the result of calling @var{function}. As with
@code{funcall}, @var{function} must either be a Lisp function or a
primitive function; special forms and macros do not make sense in
@@ -789,6 +794,11 @@ primitive function; special forms and macros do not make sense in
(apply 'append '((a b c) nil (x y z) nil))
@result{} (a b c x y z)
@end group
+
+@group
+(apply '(+ 3 4))
+ @result{} 7
+@end group
@end example
For an interesting example of using @code{apply}, see @ref{Definition
@@ -2163,15 +2173,24 @@ the backquote (@pxref{Backquote}), but quotes code and accepts only
@end defmac
@defmac inline-letevals (bindings@dots{}) body@dots{}
-This is similar to @code{let} (@pxref{Local Variables}): it sets up
-local variables as specified by @var{bindings}, and then evaluates
-@var{body} with those bindings in effect. Each element of
-@var{bindings} should be either a symbol or a list of the form
-@w{@code{(@var{var} @var{expr})}}; the result is to evaluate
-@var{expr} and bind @var{var} to the result. The tail of
-@var{bindings} can be either @code{nil} or a symbol which should hold
-a list of arguments, in which case each argument is evaluated, and the
-symbol is bound to the resulting list.
+This provides a convenient way to ensure that the arguments to an
+inlined function are evaluated exactly once, as well as to create
+local variables.
+
+It's similar to @code{let} (@pxref{Local Variables}): It sets up local
+variables as specified by @var{bindings}, and then evaluates
+@var{body} with those bindings in effect.
+
+Each element of @var{bindings} should be either a symbol or a list of
+the form @w{@code{(@var{var} @var{expr})}}; the result is to evaluate
+@var{expr} and bind @var{var} to the result. However, when an element
+of @var{bindings} is just a symbol @var{var}, the result of evaluating
+@var{var} is re-bound to @var{var} (which is quite different from the
+way @code{let} works).
+
+The tail of @var{bindings} can be either @code{nil} or a symbol which
+should hold a list of arguments, in which case each argument is
+evaluated, and the symbol is bound to the resulting list.
@end defmac
@defmac inline-const-p expression
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 9b3c4fcb23d..d4505d5c3ff 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -220,7 +220,8 @@ in the *Help* buffer."
@group
;; @r{Display the data.}
- (help-setup-xref (list 'describe-symbols pattern) (interactive-p))
+ (help-setup-xref (list 'describe-symbols pattern)
+ (called-interactively-p 'interactive))
(with-help-window (help-buffer)
(mapcar describe-func (sort sym-list 'string<)))))
@end group
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index e5b535bdab2..fed9612e329 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1228,9 +1228,9 @@ the @var{runtime} structure with the value compiled into the module:
@example
int
-emacs_module_init (struct emacs_runtime *ert)
+emacs_module_init (struct emacs_runtime *runtime)
@{
- if (ert->size < sizeof (*ert))
+ if (runtime->size < sizeof (*runtime))
return 1;
@}
@end example
@@ -1247,7 +1247,7 @@ assumes it is part of the @code{emacs_module_init} function shown
above:
@example
- emacs_env *env = ert->get_environment (ert);
+ emacs_env *env = runtime->get_environment (runtime);
if (env->size < sizeof (*env))
return 2;
@end example
@@ -1264,7 +1264,7 @@ Emacs, by comparing the size of the environment passed by Emacs with
known sizes, like this:
@example
- emacs_env *env = ert->get_environment (ert);
+ emacs_env *env = runtime->get_environment (runtime);
if (env->size >= sizeof (struct emacs_env_26))
emacs_version = 26; /* Emacs 26 or later. */
else if (env->size >= sizeof (struct emacs_env_25))
@@ -1314,7 +1314,8 @@ subsection describes how to write such @dfn{module functions}.
A module function has the following general form and signature:
-@deftypefn Function emacs_value module_func (emacs_env *@var{env}, ptrdiff_t @var{nargs}, emacs_value *@var{args}, void *@var{data})
+@deftypefn Function emacs_value emacs_function (emacs_env *@var{env}, ptrdiff_t @var{nargs}, emacs_value *@var{args}, void *@var{data})
+@tindex emacs_function
The @var{env} argument provides a pointer to the @acronym{API}
environment, needed to access Emacs objects and functions. The
@var{nargs} argument is the required number of arguments, which can be
@@ -1323,7 +1324,7 @@ of the argument number), and @var{args} is a pointer to the array of
the function arguments. The argument @var{data} points to additional
data required by the function, which was arranged when
@code{make_function} (see below) was called to create an Emacs
-function from @code{module_func}.
+function from @code{emacs_function}.
Module functions use the type @code{emacs_value} to communicate Lisp
objects between Emacs and the module (@pxref{Module Values}). The
@@ -1338,6 +1339,10 @@ However, if the user typed @kbd{C-g}, or if the module function or its
callees signaled an error or exited nonlocally (@pxref{Module
Nonlocal}), Emacs will ignore the returned value and quit or throw as
it does when Lisp code encounters the same situations.
+
+The header @file{emacs-module.h} provides the type
+@code{emacs_function} as an alias type for a function pointer to a
+module function.
@end deftypefn
After writing your C code for a module function, you should make a
@@ -1348,11 +1353,11 @@ normally done in the module initialization function (@pxref{module
initialization function}), after verifying the @acronym{API}
compatibility.
-@deftypefn Function emacs_value make_function (emacs_env *@var{env}, ptrdiff_t @var{min_arity}, ptrdiff_t @var{max_arity}, subr @var{func}, const char *@var{docstring}, void *@var{data})
+@deftypefn Function emacs_value make_function (emacs_env *@var{env}, ptrdiff_t @var{min_arity}, ptrdiff_t @var{max_arity}, emacs_function @var{func}, const char *@var{docstring}, void *@var{data})
@vindex emacs_variadic_function
This returns an Emacs function created from the C function @var{func},
-whose signature is as described for @code{module_func} above (assumed
-here to be @code{typedef}'ed as @code{subr}). The arguments
+whose signature is as described for @code{emacs_function} above.
+The arguments
@var{min_arity} and @var{max_arity} specify the minimum and maximum
number of arguments that @var{func} can accept. The @var{max_arity}
argument can have the special value @code{emacs_variadic_function},
@@ -1388,7 +1393,7 @@ Combining the above steps, code that arranges for a C function
look like this, as part of the module initialization function:
@example
- emacs_env *env = ert->get_environment (ert);
+ emacs_env *env = runtime->get_environment (runtime);
emacs_value func = env->make_function (env, min_arity, max_arity,
module_func, docstring, data);
emacs_value symbol = env->intern (env, "module-func");
@@ -1420,28 +1425,94 @@ violations of the above requirements. @xref{Initial Options,,,emacs,
The GNU Emacs Manual}.
Using the module @acronym{API}, it is possible to define more complex
-function and data types: interactive functions, inline functions,
-macros, etc. However, the resulting C code will be cumbersome and
-hard to read. Therefore, we recommend that you limit the module code
-which creates functions and data structures to the absolute minimum,
-and leave the rest for a Lisp package that will accompany your module,
-because doing these additional tasks in Lisp is much easier, and will
-produce a much more readable code. For example, given a module
-function @code{module-func} defined as above, one way of making an
-interactive command @code{module-cmd} based on it is with the
-following simple Lisp wrapper:
+function and data types: inline functions, macros, etc. However, the
+resulting C code will be cumbersome and hard to read. Therefore, we
+recommend that you limit the module code which creates functions and
+data structures to the absolute minimum, and leave the rest for a Lisp
+package that will accompany your module, because doing these
+additional tasks in Lisp is much easier, and will produce a much more
+readable code. For example, given a module function
+@code{module-func} defined as above, one way of making a macro
+@code{module-macro} based on it is with the following simple Lisp
+wrapper:
@lisp
-(defun module-cmd (&rest args)
- "Documentation string for the command."
- (interactive @var{spec})
- (apply 'module-func args))
+(defmacro module-macro (&rest args)
+ "Documentation string for the macro."
+ (module-func args))
@end lisp
The Lisp package which goes with your module could then load the
module using the @code{load} primitive (@pxref{Dynamic Modules}) when
the package is loaded into Emacs.
+By default, module functions created by @code{make_function} are not
+interactive. To make them interactive, you can use the following
+function.
+
+@deftypefun void make_interactive (emacs_env *@var{env}, emacs_value @var{function}, emacs_value @var{spec})
+This function, which is available since Emacs 28, makes the function
+@var{function} interactive using the interactive specification
+@var{spec}. Emacs interprets @var{spec} like the argument to the
+@code{interactive} form. @ref{Using Interactive}, and
+@pxref{Interactive Codes}. @var{function} must be an Emacs module
+function returned by @code{make_function}.
+@end deftypefun
+
+Note that there is no native module support for retrieving the
+interactive specification of a module function. Use the function
+@code{interactive-form} for that. @ref{Using Interactive}. It is not
+possible to make a module function non-interactive once you have made
+it interactive using @code{make_interactive}.
+
+@anchor{Module Function Finalizers}
+If you want to run some code when a module function object (i.e., an
+object returned by @code{make_function}) is garbage-collected, you can
+install a @dfn{function finalizer}. Function finalizers are available
+since Emacs 28. For example, if you have passed some heap-allocated
+structure to the @var{data} argument of @code{make_function}, you can
+use the finalizer to deallocate the structure. @xref{Basic
+Allocation,,,libc}, and @pxref{Freeing after Malloc,,,libc}. The
+finalizer function has the following signature:
+
+@example
+void finalizer (void *@var{data})
+@end example
+
+Here, @var{data} receives the value passed to @var{data} when calling
+@code{make_function}. Note that the finalizer can't interact with
+Emacs in any way.
+
+Directly after calling @code{make_function}, the newly-created
+function doesn't have a finalizer. Use @code{set_function_finalizer}
+to add one, if desired.
+
+@deftypefun void emacs_finalizer (void *@var{ptr})
+The header @file{emacs-module.h} provides the type
+@code{emacs_finalizer} as a type alias for an Emacs finalizer
+function.
+@end deftypefun
+
+@deftypefun emacs_finalizer get_function_finalizer (emacs_env *@var{env}, emacs_value @var{arg})
+This function, which is available since Emacs 28, returns the function
+finalizer associated with the module function represented by
+@var{arg}. @var{arg} must refer to a module function, that is, an
+object returned by @code{make_function}. If no finalizer is
+associated with the function, @code{NULL} is returned.
+@end deftypefun
+
+@deftypefun void set_function_finalizer (emacs_env *@var{env}, emacs_value @var{arg}, emacs_finalizer @var{fin})
+This function, which is available since Emacs 28, sets the function
+finalizer associated with the module function represented by @var{arg}
+to @var{fin}. @var{arg} must refer to a module function, that is, an
+object returned by @code{make_function}. @var{fin} can either be
+@code{NULL} to clear @var{arg}'s function finalizer, or a pointer to a
+function to be called when the object represented by @var{arg} is
+garbage-collected. At most one function finalizer can be set per
+function; if @var{arg} already has a finalizer, it is replaced by
+@var{fin}.
+@end deftypefun
+
@node Module Values
@subsection Conversion Between Lisp and Module Values
@cindex module values, conversion
@@ -1541,12 +1612,11 @@ 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{time})
-This function, which is available since Emacs 27, interprets
-@var{time} as an Emacs Lisp time value and returns the corresponding
-@code{struct timespec}. @xref{Time of Day}. @code{struct timespec}
-represents a timestamp with nanosecond precision. It has the
-following members:
+@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
+timestamp with nanosecond precision. It has the following members:
@table @code
@item time_t tv_sec
@@ -1744,9 +1814,9 @@ next_prime (emacs_env *env, ptrdiff_t nargs, emacs_value *args,
@}
int
-emacs_module_init (struct emacs_runtime *ert)
+emacs_module_init (struct emacs_runtime *runtime)
@{
- emacs_env *env = ert->get_environment (ert);
+ emacs_env *env = runtime->get_environment (runtime);
emacs_value symbol = env->intern (env, "next-prime");
emacs_value func
= env->make_function (env, 1, 1, next_prime, NULL, NULL);
@@ -1773,16 +1843,15 @@ there's no requirement that @var{time} be normalized. This means that
@code{@var{time}.tv_nsec} can be negative or larger than 999,999,999.
@end deftypefn
-@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{strlen})
+@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{len})
This function creates an Emacs string from C text string pointed by
@var{str} whose length in bytes, not including the terminating null
-byte, is @var{strlen}. The original string in @var{str} can be either
-an @acronym{ASCII} string or a UTF-8 encoded non-@acronym{ASCII}
-string; it can include embedded null bytes, and doesn't have to end in
-a terminating null byte at @code{@var{str}[@var{strlen}]}. The
-function raises the @code{overflow-error} error condition if
-@var{strlen} is negative or exceeds the maximum length of an Emacs
-string.
+byte, is @var{len}. The original string in @var{str} can be either an
+@acronym{ASCII} string or a UTF-8 encoded non-@acronym{ASCII} string;
+it can include embedded null bytes, and doesn't have to end in a
+terminating null byte at @code{@var{str}[@var{len}]}. The function
+raises the @code{overflow-error} error condition if @var{len} is
+negative or exceeds the maximum length of an Emacs string.
@end deftypefn
The @acronym{API} does not provide functions to manipulate Lisp data
@@ -1839,27 +1908,32 @@ 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 val)
+@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{val}.
+by @var{arg}.
@end deftypefn
-@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{value}, void *@var{ptr})
+@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{arg}, void *@var{ptr})
This function sets the C pointer embedded in the @code{user-ptr}
-object represented by @var{value} to @var{ptr}.
+object represented by @var{arg} to @var{ptr}.
@end deftypefn
-@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value val)
+@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value @var{arg})
This function returns the finalizer of the @code{user-ptr} object
-represented by @var{val}, or @code{NULL} if it doesn't have a finalizer.
+represented by @var{arg}, or @code{NULL} if it doesn't have a
+finalizer.
@end deftypefn
-@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{val}, emacs_finalizer @var{fin})
+@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{arg}, emacs_finalizer @var{fin})
This function changes the finalizer of the @code{user-ptr} object
-represented by @var{val} to be @var{fin}. If @var{fin} is a
-@code{NULL} pointer, the @code{user-ptr} object will have no finalizer.
+represented by @var{arg} to be @var{fin}. If @var{fin} is a
+@code{NULL} pointer, the @code{user-ptr} object will have no
+finalizer.
@end deftypefn
+Note that the @code{emacs_finalizer} type works for both user pointer
+an module function finalizers. @xref{Module Function Finalizers}.
+
@node Module Misc
@subsection Miscellaneous Convenience Functions for Modules
@@ -1870,20 +1944,20 @@ be called via the @code{emacs_env} pointer. Description of functions
that were introduced after Emacs 25 calls out the first version where
they became available.
-@deftypefn Function bool eq (emacs_env *@var{env}, emacs_value @var{val1}, emacs_value @var{val2})
+@deftypefn Function bool eq (emacs_env *@var{env}, emacs_value @var{a}, emacs_value @var{b})
This function returns @code{true} if the Lisp objects represented by
-@var{val1} and @var{val2} are identical, @code{false} otherwise. This
-is the same as the Lisp function @code{eq} (@pxref{Equality
-Predicates}), but avoids the need to intern the objects represented by
-the arguments.
+@var{a} and @var{b} are identical, @code{false} otherwise. This is
+the same as the Lisp function @code{eq} (@pxref{Equality Predicates}),
+but avoids the need to intern the objects represented by the
+arguments.
There are no @acronym{API} functions for other equality predicates, so
you will need to use @code{intern} and @code{funcall}, described
below, to perform more complex equality tests.
@end deftypefn
-@deftypefn Function bool is_not_nil (emacs_env *@var{env}, emacs_value @var{val})
-This function tests whether the Lisp object represented by @var{val}
+@deftypefn Function bool is_not_nil (emacs_env *@var{env}, emacs_value @var{arg})
+This function tests whether the Lisp object represented by @var{arg}
is non-@code{nil}; it returns @code{true} or @code{false} accordingly.
Note that you could implement an equivalent test by using
@@ -1892,12 +1966,12 @@ then use @code{eq}, described above, to test for equality. But using
this function is more convenient.
@end deftypefn
-@deftypefn Function emacs_value type_of (emacs_env *@var{env}, emacs_value @code{object})
-This function returns the type of @var{object} as a value that
-represents a symbol: @code{string} for a string, @code{integer} for an
-integer, @code{process} for a process, etc. @xref{Type Predicates}.
-You can use @code{intern} and @code{eq} to compare against known type
-symbols, if your code needs to depend on the object type.
+@deftypefn Function emacs_value type_of (emacs_env *@var{env}, emacs_value @code{arg})
+This function returns the type of @var{arg} as a value that represents
+a symbol: @code{string} for a string, @code{integer} for an integer,
+@code{process} for a process, etc. @xref{Type Predicates}. You can
+use @code{intern} and @code{eq} to compare against known type symbols,
+if your code needs to depend on the object type.
@end deftypefn
@anchor{intern}
@@ -1917,8 +1991,7 @@ calling the more powerful Emacs @code{intern} function
emacs_value fintern = env->intern (env, "intern");
emacs_value sym_name =
env->make_string (env, name_str, strlen (name_str));
-emacs_value intern_args[] = @{ sym_name, env->intern (env, "nil") @};
-emacs_value symbol = env->funcall (env, fintern, 2, intern_args);
+emacs_value symbol = env->funcall (env, fintern, 1, &sym_name);
@end example
@end deftypefn
@@ -1967,6 +2040,20 @@ variable values and buffer content may have been modified in arbitrary
ways.
@end deftypefn
+@anchor{open_channel}
+@deftypefun int open_channel (emacs_env *@var{env}, emacs_value @var{pipe_process})
+This function, which is available since Emacs 28, opens a channel to
+an existing pipe process. @var{pipe_process} must refer to an
+existing pipe process created by @code{make-pipe-process}. @ref{Pipe
+Processes}. If successful, the return value will be a new file
+descriptor that you can use to write to the pipe. Unlike all other
+module functions, you can use the returned file descriptor from
+arbitrary threads, even if no module environment is active. You can
+use the @code{write} function to write to the file descriptor. Once
+done, close the file descriptor using @code{close}. @ref{Low-Level
+I/O,,,libc}.
+@end deftypefun
+
@node Module Nonlocal
@subsection Nonlocal Exits in Modules
@cindex nonlocal exits, in modules
@@ -2071,11 +2158,12 @@ One use of this function is when you want to re-throw a non-local exit
from one of the called @acronym{API} or Lisp functions.
@end deftypefn
-@deftypefn Function void non_local_exit_signal (emacs_env *@var{env}, emacs_value @var{error}, emacs_value @var{data})
-This function signals the error represented by @var{error} with the
-specified error data @var{data}. The module function should return
-soon after calling this function. This function could be useful,
-e.g., for signaling errors from module functions to Emacs.
+@deftypefn Function void non_local_exit_signal (emacs_env *@var{env}, emacs_value @var{symbol}, emacs_value @var{data})
+This function signals the error represented by the error symbol
+@var{symbol} with the specified error data @var{data}. The module
+function should return soon after calling this function. This
+function could be useful, e.g., for signaling errors from module
+functions to Emacs.
@end deftypefn
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 0dc7c804e72..a4b479597ea 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -87,7 +87,9 @@ you are criticizing.
@cindex bugs
@cindex suggestions
-Please send comments and corrections using @kbd{M-x report-emacs-bug}.
+Please send comments and corrections using @kbd{M-x
+report-emacs-bug}. If you wish to contribute new code (or send a
+patch to fix a problem), use @kbd{M-x submit-emacs-patch}).
@node Lisp History
@section Lisp History
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 1e81fb1dc52..130ff0d8671 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1846,8 +1846,11 @@ local map.
@cindex scanning keymaps
@cindex keymaps, scanning
- This section describes functions used to scan all the current keymaps
-for the sake of printing help information.
+ This section describes functions used to scan all the current
+keymaps for the sake of printing help information. To display the
+bindings in a particular keymap, you can use the
+@code{describe-keymap} command (@pxref{Misc Help, , Other Help
+Commands, emacs, The GNU Emacs Manual})
@defun accessible-keymaps keymap &optional prefix
This function returns a list of all the keymaps that can be reached (via
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 2739d10ece9..6833af9c262 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -1170,10 +1170,13 @@ extension, a.k.a.@: ``suffix''. This suffix is platform-dependent.
@defvar module-file-suffix
This variable holds the system-dependent value of the file-name
-extension of the module files. Its value is @file{.so} on POSIX hosts
-and @file{.dll} on MS-Windows.
+extension of the module files. Its value is @file{.so} on POSIX
+hosts, @file{.dylib} on macOS, and @file{.dll} on MS-Windows.
@end defvar
+ On macOS, dynamic modules can also have the suffix @file{.so} in
+addition to @file{.dylib}.
+
@findex emacs_module_init
@vindex plugin_is_GPL_compatible
Every dynamic module should export a C-callable function named
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index ecab882fed7..d00acd0ded3 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -316,8 +316,22 @@ input before returning it. However,
@code{read-no-blanks-input} (see below), as well as
@code{read-minibuffer} and related functions (@pxref{Object from
Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
-functions that do minibuffer input with completion, discard text
-properties unconditionally, regardless of the value of this variable.
+functions that do minibuffer input with completion, remove the @code{face}
+property unconditionally, regardless of the value of this variable.
+
+If this variable is non-@code{nil}, most text properties on strings
+from the completion table are preserved---but only on the part of the
+strings that were completed.
+
+@lisp
+(let ((minibuffer-allow-text-properties t))
+ (completing-read "String: " (list (propertize "foobar" 'data 'zot))))
+=> #("foobar" 3 6 (data zot))
+@end lisp
+
+In this example, the user typed @samp{foo} and then hit the @kbd{TAB}
+key, so the text properties are only preserved on the last three
+characters.
@end defvar
@defvar minibuffer-local-map
@@ -411,6 +425,39 @@ following bindings, in addition to those of @code{minibuffer-local-map}:
@end table
@end defvar
+@vindex minibuffer-default-prompt-format
+@defun format-prompt prompt default &rest format-args
+Format @var{prompt} with default value @var{default} according to the
+@code{minibuffer-default-prompt-format} variable.
+
+@code{minibuffer-default-prompt-format} is a format string (defaulting
+to @samp{" (default %s)"} that says how the ``default'' bit in prompts
+like @samp{"Local filename (default somefile): "} are to be formatted.
+
+To allow the users to customize how this is displayed, code that
+prompts the user for a value (and has a default) should look something
+along the lines of this code snippet:
+
+@lisp
+(read-file-name
+ (format-prompt "Local filename" file)
+ nil file)
+@end lisp
+
+If @var{format-args} is @code{nil}, @var{prompt} is used as a literal
+string. If @var{format-args} is non-@code{nil}, @var{prompt} is used
+as a format control string, and @var{prompt} and @var{format-args} are
+passed to @code{format} (@pxref{Formatting Strings}).
+
+@code{minibuffer-default-prompt-format} can be @samp{""}, in which
+case no default values are displayed.
+
+If @var{default} is @code{nil}, there is no default value, and
+therefore no ``default value'' string is included in the result value.
+If @var{default} is a non-@code{nil} list, the first element of the
+list is used in the prompt.
+@end defun
+
@node Object from Minibuffer
@section Reading Lisp Objects with the Minibuffer
@cindex minibuffer input, reading lisp objects
@@ -646,6 +693,15 @@ A history list for variable-name arguments read by
@code{read-variable}.
@end defvar
+@defvar read-number-history
+A history list for numbers read by @code{read-number}.
+@end defvar
+
+@defvar goto-line-history
+A history list for arguments to @code{goto-line}. This variable is
+buffer local.
+@end defvar
+
@c Less common: coding-system-history, input-method-history,
@c command-history, grep-history, grep-find-history,
@c read-envvar-name-history, setenv-history, yes-or-no-p-history.
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index de40fa7f963..be2ee5721c2 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -469,9 +469,10 @@ variable @code{imenu-generic-expression}, for the two variables
@code{imenu-create-index-function} (@pxref{Imenu}).
@item
-The mode can specify a local value for
-@code{eldoc-documentation-function} to tell ElDoc mode how to handle
-this mode.
+The mode can tell ElDoc mode how to retrieve different types of
+documentation for whatever is at point, by adding one or more
+buffer-local entries to the special hook
+@code{eldoc-documentation-functions}.
@item
The mode can specify how to complete various keywords by adding one or
@@ -1352,19 +1353,11 @@ illustrate how these modes are written.
@end smallexample
The three modes for Lisp share much of their code. For instance,
-each calls the following function to set various variables:
-
-@smallexample
-@group
-(defun lisp-mode-variables (&optional syntax keywords-case-insensitive elisp)
- (when syntax
- (set-syntax-table lisp-mode-syntax-table))
- @dots{}
-@end group
-@end smallexample
+Lisp mode and Emacs Lisp mode inherit from Lisp Data mode and Lisp
+Interaction Mode inherits from Emacs Lisp mode.
@noindent
-Amongst other things, this function sets up the @code{comment-start}
+Amongst other things, Lisp Data mode sets up the @code{comment-start}
variable to handle Lisp comments:
@smallexample
@@ -1414,7 +1407,7 @@ Finally, here is the major mode command for Lisp mode:
@smallexample
@group
-(define-derived-mode lisp-mode prog-mode "Lisp"
+(define-derived-mode lisp-mode lisp-data-mode "Lisp"
"Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
Commands:
Delete converts tabs to spaces as it moves back.
@@ -1425,10 +1418,9 @@ Note that `run-lisp' may be used either to start an inferior Lisp job
or to switch back to an existing one."
@end group
@group
- (lisp-mode-variables nil t)
(setq-local find-tag-default-function 'lisp-find-tag-default)
(setq-local comment-start-skip
- "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
+ "\\(\\(^\\|[^\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
(setq imenu-case-fold-search t))
@end group
@end smallexample
@@ -2174,6 +2166,29 @@ Mode line construct for miscellaneous information. By default, this
shows the information specified by @code{global-mode-string}.
@end defvar
+@defvar mode-line-position-line-format
+The format used to display line numbers when @code{line-number-mode}
+(@pxref{Optional Mode Line,,, emacs, The GNU Emacs Manual}) is
+switched on. @samp{%l} in the format will be replaced with the line
+number.
+@end defvar
+
+@defvar mode-line-position-column-format
+The format used to display column numbers when
+@code{column-number-mode} (@pxref{Optional Mode Line,,, emacs, The GNU
+Emacs Manual}) is switched on. @samp{%c} in the format will be
+replaced with the column number, and this is zero-based if
+@code{column-number-indicator-zero-based} is non-@code{nil}, and
+one-based if @code{column-number-indicator-zero-based} is @code{nil}.
+@end defvar
+
+@defvar mode-line-position-column-line-format
+The format used to display column numbers when both
+@code{line-number-mode} and @code{column-number-mode} are switched on.
+See the previous two variables for the meaning of the @samp{%l} and
+@samp{%c} format specs.
+@end defvar
+
@defvar minor-mode-alist
@anchor{Definition of minor-mode-alist}
This variable holds an association list whose elements specify how the
@@ -2674,6 +2689,7 @@ Setting this variable makes it buffer-local in the current buffer.
@node Font Lock Mode
@section Font Lock Mode
@cindex Font Lock mode
+@cindex syntax highlighting and coloring
@dfn{Font Lock mode} is a buffer-local minor mode that automatically
attaches @code{face} properties to certain parts of the buffer based on
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 5c5f89eb433..83066744121 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -2339,8 +2339,12 @@ same sequence of character codes and all these codes are in the range
@end group
@end example
-However, two distinct buffers are never considered @code{equal}, even if
-their textual contents are the same.
+The @code{equal} function recursively compares the contents of objects
+if they are integers, strings, markers, vectors, bool-vectors,
+byte-code function objects, char-tables, records, or font objects.
+Other objects are considered @code{equal} only if they are @code{eq}.
+For example, two distinct buffers are never considered @code{equal},
+even if their textual contents are the same.
@end defun
For @code{equal}, equality is defined recursively; for example, given
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index b31ab87ff17..504f0dfb23e 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1701,7 +1701,8 @@ following form:
@noindent
The format of this list is the same as what @code{decode-time} accepts
(@pxref{Time Conversion}), and is described in more detail there. Any
-element that cannot be determined from the input will be set to
+@code{dst} element that cannot be determined from the input is set to
+@minus{}1, and any other unknown element is set to
@code{nil}. The argument @var{string} should resemble an RFC 822 (or later) or
ISO 8601 string, like ``Fri, 25 Mar 2016 16:24:56 +0100'' or
``1998-09-12T12:21:54-0200'', but this function will attempt to parse
@@ -2193,9 +2194,9 @@ cause anything special to happen.
@findex list-timers
The @code{list-timers} command lists all the currently active timers.
-There's only one command available in the buffer displayed: @kbd{c}
-(@code{timer-list-cancel}) that will cancel the timer on the line
-under point.
+The command @kbd{c} (@code{timer-list-cancel}) will cancel the timer
+on the line under point. You can sort the list by column using the
+command @kbd{S} (@code{tabulated-list-sort}).
@node Idle Timers
@section Idle Timers
@@ -2686,9 +2687,9 @@ Emacs is restarted by the session manager.
@group
(defun save-yourself-test ()
- (insert "(save-current-buffer
- (switch-to-buffer \"*scratch*\")
- (insert \"I am restored\"))")
+ (insert
+ (format "%S" '(with-current-buffer "*scratch*"
+ (insert "I am restored"))))
nil)
@end group
@end example
@@ -3137,7 +3138,7 @@ being reported. For example:
@end group
@group
-(set-file-modes "/tmp/foo" (default-file-modes))
+(set-file-modes "/tmp/foo" (default-file-modes) 'nofollow)
@result{} Event (35025468 attribute-changed "/tmp/foo")
@end group
@end example
diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index d7856ce73e3..751adcff5a8 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -332,6 +332,8 @@ if provided; otherwise @var{n} defaults to @code{nil}.
@node Text Lines
@subsection Motion by Text Lines
@cindex lines
+@cindex logical lines, moving by
+@cindex physical lines, moving by
Text lines are portions of the buffer delimited by newline characters,
which are regarded as part of the previous line. The first text line
@@ -411,7 +413,7 @@ function counts that line as one line successfully moved.
In an interactive call, @var{count} is the numeric prefix argument.
@end deffn
-@defun count-lines start end
+@defun count-lines start end &optional ignore-invisible-lines
@cindex lines in region
@anchor{Definition of count-lines}
This function returns the number of lines between the positions
@@ -420,6 +422,9 @@ This function returns the number of lines between the positions
1, even if @var{start} and @var{end} are on the same line. This is
because the text between them, considered in isolation, must contain at
least one line unless it is empty.
+
+If the optional @var{ignore-invisible-lines} is non-@code{nil},
+invisible lines will not be included in the count.
@end defun
@deffn Command count-words start end
@@ -515,6 +520,7 @@ beginning or end of a line.
@node Screen Lines
@subsection Motion by Screen Lines
@cindex screen lines, moving by
+@cindex visual lines, moving by
The line functions in the previous section count text lines, delimited
only by newline characters. By contrast, these functions count screen
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 6970f718ee0..855df4b9260 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -477,6 +477,22 @@ You should only ever change this variable with a let-binding; never
with @code{setq}.
@end defvar
+@defopt process-file-return-signal-string
+This user option indicates whether a call of @code{process-file}
+returns a string describing the signal interrupting a remote process.
+
+When a process returns an exit code greater than 128, it is
+interpreted as a signal. @code{process-file} requires to return a
+string describing this signal.
+
+Since there are processes violating this rule, returning exit codes
+greater than 128 which are not bound to a signal, @code{process-file}
+returns always the exit code as natural number for remote processes.
+Setting this user option to non-nil forces @code{process-file} to
+interpret such exit codes as signals, and to return a corresponding
+string.
+@end defopt
+
@defun call-process-region start end program &optional delete destination display &rest args
This function sends the text from @var{start} to @var{end} as
standard input to a process running @var{program}. It deletes the text
@@ -587,6 +603,11 @@ This function works by calling @code{call-process}, so program output
is decoded in the same way as for @code{call-process}.
@end defun
+@defun process-lines-ignore-status program &rest args
+This function is just like @code{process-lines}, but does not signal
+an error if @var{program} exits with a non-zero exit status.
+@end defun
+
@node Asynchronous Processes
@section Creating an Asynchronous Process
@cindex asynchronous subprocess
@@ -743,6 +764,7 @@ Some file name handlers may not support @code{make-process}. In such
cases, this function does nothing and returns @code{nil}.
@end defun
+@anchor{Pipe Processes}
@defun make-pipe-process &rest args
This function creates a bidirectional pipe which can be attached to a
child process. This is useful with the @code{:stderr} keyword of
@@ -1554,7 +1576,8 @@ from previous output.
@defun set-process-buffer process buffer
This function sets the buffer associated with @var{process} to
@var{buffer}. If @var{buffer} is @code{nil}, the process becomes
-associated with no buffer.
+associated with no buffer; if non-@code{nil}, the process mark will be
+set to point to the end of @var{buffer}.
@end defun
@defun get-buffer-process buffer-or-name
@@ -2426,18 +2449,15 @@ server is stopped; a non-@code{nil} value means yes.
@cindex encrypted network connections
@cindex @acronym{TLS} network connections
@cindex @acronym{STARTTLS} network connections
-Emacs can create encrypted network connections, using either built-in
-or external support. The built-in support uses the GnuTLS
-Transport Layer Security Library; see
+Emacs can create encrypted network connections, using the built-in
+support for the GnuTLS Transport Layer Security Library; see
@uref{https://www.gnu.org/software/gnutls/, the GnuTLS project page}.
If your Emacs was compiled with GnuTLS support, the function
@code{gnutls-available-p} is defined and returns non-@code{nil}. For
more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}.
-The external support uses the @file{starttls.el} library, which
-requires a helper utility such as @command{gnutls-cli} to be installed
-on the system. The @code{open-network-stream} function can
-transparently handle the details of creating encrypted connections for
-you, using whatever support is available.
+The @code{open-network-stream} function can transparently handle the
+details of creating encrypted connections for you, using whatever
+support is available.
@defun open-network-stream name buffer host service &rest parameters
This function opens a TCP connection, with optional encryption, and
@@ -2465,6 +2485,12 @@ that are mainly relevant to encrypted connections:
@item :nowait @var{boolean}
If non-@code{nil}, try to make an asynchronous connection.
+@item :coding @var{coding}
+Use this to set the coding systems used by the network process, in
+preference to binding @code{coding-system-for-read} or
+@code{coding-system-for-write}. @xref{Network Processes}, for
+details.
+
@item :type @var{type}
The type of connection. Options are:
@@ -2491,7 +2517,10 @@ If non-@code{nil}, always ask for the server's capabilities, even when
doing a @samp{plain} connection.
@item :capability-command @var{capability-command}
-Command string to query the host capabilities.
+Command to query the host capabilities. This can either be a string
+(which will then be sent verbatim to the server), or a function
+(called with a single parameter; the "greeting" from the server when
+connecting), and should return a string.
@item :end-of-command @var{regexp}
@itemx :end-of-capability @var{regexp}
diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index c8a12bdd66b..b4fec6d1fd6 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -342,7 +342,7 @@ this choice, the rest of the regexp matches successfully.
long time, if they lead to ambiguous matching. For
example, trying to match the regular expression @samp{\(x+y*\)*a}
against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could
-take hours before it ultimately fails. Emacs must try each way of
+take hours before it ultimately fails. Emacs may try each way of
grouping the @samp{x}s before concluding that none of them can work.
In general, avoid expressions that can match the same string in
multiple ways.
@@ -2542,7 +2542,7 @@ and replace them, the best way is to write an explicit loop using
description of @code{replace-match}.
However, replacing matches in a string is more complex, especially
-if you want to do it efficiently. So Emacs provides a function to do
+if you want to do it efficiently. So Emacs provides two functions to do
this.
@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
@@ -2566,6 +2566,13 @@ replacement string. The match data at this point are the result
of matching @var{regexp} against a substring of @var{string}.
@end defun
+@defun string-replace fromstring tostring instring
+This function returns a string equal to @var{instring} where any
+occurrences of @var{fromstring} have been replaced with
+@var{tostring}. It may return one of its arguments.
+Case is significant, and text properties are ignored.
+@end defun
+
If you want to write a command along the lines of @code{query-replace},
you can use @code{perform-replace} to do the work.
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 0dc47f30c43..0f157c39d63 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -656,6 +656,16 @@ optional argument @var{ignore-case} is non-@code{nil}, the comparison
ignores case differences.
@end defun
+@defun string-search needle haystack &optional start-pos
+Return the position of the first instance of @var{needle} in
+@var{haystack}, both of which are strings. If @var{start-pos} is
+non-@code{nil}, start searching from that position in @var{needle}.
+Return @code{nil} if no match was found.
+This function only considers the characters in the strings when doing
+the comparison; text properties are ignored. Matching is always
+case-sensitive.
+@end defun
+
@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
This function compares a specified part of @var{string1} with a
specified part of @var{string2}. The specified part of @var{string1}
@@ -1157,7 +1167,7 @@ The function @code{format-spec} described in this section performs a
similar function to @code{format}, except it operates on format
control strings that use arbitrary specification characters.
-@defun format-spec template spec-alist &optional only-present
+@defun format-spec template spec-alist &optional ignore-missing
This function returns a string produced from the format string
@var{template} according to conversions specified in @var{spec-alist},
which is an alist (@pxref{Association Lists}) of the form
@@ -1190,12 +1200,15 @@ The order of specifications in @var{template} need not correspond to
the order of associations in @var{spec-alist}.
@end itemize
-The optional argument @var{only-present} indicates how to handle
+The optional argument @var{ignore-missing} indicates how to handle
specification characters in @var{template} that are not found in
@var{spec-alist}. If it is @code{nil} or omitted, the function
-signals an error. Otherwise, those format specifications and any
-occurrences of @samp{%%} in @var{template} are left verbatim in the
-output, including their text properties, if any.
+signals an error; if it is @code{ignore}, those format specifications
+are left verbatim in the output, including their text properties, if
+any; if it is @code{delete}, those format specifications are removed
+from the output; any other non-@code{nil} value is handled like
+@code{ignore}, but any occurrences of @samp{%%} are also left verbatim
+in the output.
@end defun
The syntax of format specifications accepted by @code{format-spec} is
@@ -1243,7 +1256,7 @@ the right rather than the left.
@item <
This flag causes the substitution to be truncated on the left to the
-given width, if specified.
+given width and precision, if specified.
@item >
This flag causes the substitution to be truncated on the right to the
@@ -1262,9 +1275,12 @@ The result of using contradictory flags (for instance, both upper and
lower case) is undefined.
As is the case with @code{format}, a format specification can include
-a width, which is a decimal number that appears after any flags. If a
-substitution contains fewer characters than its specified width, it is
-padded on the left:
+a width, which is a decimal number that appears after any flags, and a
+precision, which is a decimal-point @samp{.} followed by a decimal
+number that appears after any flags and width.
+
+If a substitution contains fewer characters than its specified width,
+it is padded on the left:
@example
@group
@@ -1274,6 +1290,17 @@ padded on the left:
@end group
@end example
+If a substitution contains more characters than its specified
+precision, it is truncated on the right:
+
+@example
+@group
+(format-spec "%.2a is truncated on the right"
+ '((?a . "alpha")))
+ @result{} "al is truncated on the right"
+@end group
+@end example
+
Here is a more complicated example that combines several
aforementioned features:
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index c4e92bdcedb..722c044b1a1 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4813,11 +4813,9 @@ When @var{noerror} is non-@code{nil}, this function silently uses
@code{raw-text} coding instead.
@item (@code{iv-auto} @var{length})
-This will generate an IV (Initialization Vector) of the specified
-length using the GnuTLS @code{GNUTLS_RND_NONCE} generator and pass it
-to the function. This ensures that the IV is unpredictable and
-unlikely to be reused in the same session. The actual value of the IV
-is returned by the function as described below.
+This generates a random IV (Initialization Vector) of the specified
+length and passes it to the function. This ensures that the IV is
+unpredictable and unlikely to be reused in the same session.
@end table
@@ -5101,6 +5099,9 @@ The following are functions for altering the @acronym{DOM}.
@item dom-set-attribute @var{node} @var{attribute} @var{value}
Set the @var{attribute} of the node to @var{value}.
+@item dom-remove-attribute @var{node} @var{attribute}
+Remove @var{attribute} from @var{node}.
+
@item dom-append-child @var{node} @var{child}
Append @var{child} as the last child of @var{node}.
@@ -5153,6 +5154,11 @@ Utility functions:
@item dom-pp @var{dom} &optional @var{remove-empty}
Pretty-print @var{dom} at point. If @var{remove-empty}, don't print
textual nodes that just contain white-space.
+
+@item dom-print @var{dom} &optional @var{pretty} @var{xml}
+Print @var{dom} at point. If @var{xml} is non-@code{nil}, print as
+@acronym{XML}; otherwise, print as @acronym{HTML}. If @var{pretty} is
+non-@code{nil}, indent the @acronym{HTML}/@acronym{XML} logically.
@end table
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 5b09b2ccea6..1826e8f7b42 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -918,29 +918,56 @@ values. It is much better to convert such comments to documentation
strings, though.
@item ;;;
-Comments that start with three semicolons, @samp{;;;}, should start at
-the left margin. We use them
-for comments which should be considered a
-heading by Outline minor mode. By default, comments starting with
-at least three semicolons (followed by a single space and a
-non-whitespace character) are considered headings, comments starting
-with two or fewer are not. Historically, triple-semicolon comments have
-also been used for commenting out lines within a function, but this use
-is discouraged.
-
-When commenting out entire functions, use two semicolons.
-
-@item ;;;;
-Comments that start with four (or more) semicolons, @samp{;;;;},
-should be aligned to the left margin and are used for headings of
-major sections of a program. For example:
+
+Comments that start with three (or more) semicolons, @samp{;;;},
+should start at the left margin. We use them for comments that should
+be considered a heading by Outline minor mode. By default, comments
+starting with at least three semicolons (followed by a single space
+and a non-whitespace character) are considered section headings,
+comments starting with two or fewer are not.
+
+(Historically, triple-semicolon comments have also been used for
+commenting out lines within a function, but this use is discouraged in
+favor of using just two semicolons. This also applies when commenting
+out entire functions; when doing that use two semicolons as well.)
+
+Three semicolons are used for top-level sections, four for
+sub-sections, five for sub-sub-sections and so on.
+
+Typically libraries have at least four top-level sections. For
+example when the bodies of all of these sections are hidden:
@smallexample
-;;;; The kill ring
+@group
+;;; backquote.el --- implement the ` Lisp construct...
+;;; Commentary:...
+;;; Code:...
+;;; backquote.el ends here
+@end group
@end smallexample
-If you wish to have sub-headings under these heading, use more
-semicolons to nest these sub-headings.
+(In a sense the last line is not a section heading as it must
+never be followed by any text; after all it marks the end of the
+file.)
+
+For longer libraries it is advisable to split the code into multiple
+sections. This can be done by splitting the @samp{Code:} section into
+multiple sub-sections. Even though that was the only recommended
+approach for a long time, many people have chosen to use multiple
+top-level code sections instead. You may chose either style.
+
+Using multiple top-level code sections has the advantage that it
+avoids introducing an additional nesting level but it also means that
+the section named @samp{Code} does not contain all the code, which is
+awkward. To avoid that, you should put no code at all inside that
+section; that way it can be considered a seperator instead of a
+section heading.
+
+Finally, we recommend that you don't end headings with a colon or any
+other punctuation for that matter. For historic reasons the
+@samp{Code:} and @samp{Commentary:} headings end with a colon, but we
+recommend that you don't do the same for other headings anyway.
+
@end table
@noindent
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index abcd4bbd0f7..94c8c88796f 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -2585,8 +2585,11 @@ implemented this way:
(macroexp-let2* nil ((start from) (end to))
(funcall do `(substring ,getter ,start ,end)
(lambda (v)
- (funcall setter `(cl--set-substring
- ,getter ,start ,end ,v))))))))
+ (macroexp-let2 nil v v
+ `(progn
+ ,(funcall setter `(cl--set-substring
+ ,getter ,start ,end ,v))
+ ,v))))))))
@end example
@end defmac
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index a19f123c658..5ec23a9c876 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3048,6 +3048,16 @@ since there is no guarantee that an arbitrary caller of
@code{display-buffer} will be able to handle the case that no window
will display the buffer. @code{display-buffer-no-window} is the only
action function that cares about this entry.
+
+@vindex body-function@r{, a buffer display action alist entry}
+@item body-function
+The value must be a function taking one argument (a displayed window).
+This function can be used to fill the displayed window's body with
+some contents that might depend on dimensions of the displayed window.
+It is called @emph{after} the buffer is displayed, and @emph{before}
+the entries @code{window-height}, @code{window-width} and
+@code{preserve-size} are applied that could resize the window to fit
+it to the inserted contents.
@end table
By convention, the entries @code{window-height}, @code{window-width}
@@ -5916,10 +5926,6 @@ This function compares two window configurations as regards the
structure of windows, but ignores the values of point and the
saved scrolling positions---it can return @code{t} even if those
aspects differ.
-
-The function @code{equal} can also compare two window configurations; it
-regards configurations as unequal if they differ in any respect, even a
-saved point.
@end defun
@defun window-configuration-frame config
generated by cgit v1.2.3 (git 2.39.1) at 2025-04-19 03:37:28 +0000