diff options
Diffstat (limited to 'doc')
35 files changed, 326 insertions, 265 deletions
diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index d3fda285f26..9303b0b8dd1 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -565,12 +565,6 @@ is found there. @item HOSTNAME @vindex HOSTNAME@r{, environment variable} The name of the machine that Emacs is running on. -@c complete.el is obsolete since 24.1. -@ignore -@item INCPATH -A colon-separated list of directories. Used by the @code{complete} package -to search for files. -@end ignore @item INFOPATH @vindex INFOPATH@r{, environment variable} A colon-separated list of directories in which to search for Info files. diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 8444aef3bdd..4ecebc7a270 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -1654,6 +1654,8 @@ Customization}). (The other attributes of this face have no effect; the text shown under the cursor is drawn using the frame's background color.) To change its shape, customize the buffer-local variable @code{cursor-type}; possible values are @code{box} (the default), +@code{(box . @var{size})} (box cursor becoming a hollow box under +masked images larger than @var{size} pixels in either dimension), @code{hollow} (a hollow box), @code{bar} (a vertical bar), @code{(bar . @var{n})} (a vertical bar @var{n} pixels wide), @code{hbar} (a horizontal bar), @code{(hbar . @var{n})} (a horizontal bar @var{n} diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi index 3665faf3a8f..2c268f14fb7 100644 --- a/doc/emacs/fixit.texi +++ b/doc/emacs/fixit.texi @@ -66,6 +66,7 @@ changes have already been undone, the undo command signals an error. @cindex redo @findex undo-only +@findex undo-redo Any command other than an undo command breaks the sequence of undo commands. Starting from that moment, the entire sequence of undo commands that you have just performed are themselves placed into the @@ -76,7 +77,9 @@ undo commands. Alternatively, if you want to resume undoing, without redoing previous undo commands, use @kbd{M-x undo-only}. This is like -@code{undo}, but will not redo changes you have just undone. +@code{undo}, but will not redo changes you have just undone. To +complement it, @kbd{M-x undo-redo} will undo previous undo commands +(and will not record itself as an undoable command). If you notice that a buffer has been modified accidentally, the easiest way to recover is to type @kbd{C-/} repeatedly until the stars diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index fce6720b934..49c53c5cbc0 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -601,6 +601,11 @@ is @key{ESC}, because @kbd{@key{ESC} C-h} is actually @kbd{C-M-h}, which marks a defun. However, @w{@kbd{@key{ESC} @key{F1}}} and @w{@kbd{@key{ESC} ?}} work fine.) +@findex describe-keymap +Finally, @kbd{M-x describe-keymap} prompts for the name of a keymap, +with completion, and displays a listing of all key bindings in that +keymap. + @node Help Files @section Help Files diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi index fc2d2d8c84d..b18c334acf4 100644 --- a/doc/emacs/m-x.texi +++ b/doc/emacs/m-x.texi @@ -72,6 +72,10 @@ number, in which case Emacs will show the binding for that many seconds before removing it from display. The default behavior is to display the binding for 2 seconds. +Additionally, when @code{suggest-key-bindings} is non-@code{nil}, the +completion list of @kbd{M-x} shows equivalent key bindings for all +commands that have them. + @vindex extended-command-suggest-shorter Commands that don't have key bindings, can still be invoked after typing less than their full name at the @samp{M-x} prompt. Emacs diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 6bf4fc7e10c..db3cf317ff1 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -151,27 +151,6 @@ Refresh the package list (@code{revert-buffer}). This fetches the list of available packages from the package archive again, and redisplays the package list. -@item / k -@kindex / k @r{(Package Menu)} -@findex package-menu-filter-by-keyword -Filter the package list by keyword -(@code{package-menu-filter-by-keyword}). This prompts for a keyword -(e.g., @samp{games}), then shows only the packages that relate to that -keyword. - -@item / n -@kindex / n @r{(Package Menu)} -@findex package-menu-filter-by-name -Filter the package list by name (@code{package-menu-filter-by-name}). -This prompts for a string, then shows only the packages whose names -match a regexp with that value. - -@item / / -@kindex / / @r{(Package Menu)} -@findex package-menu-clear-filter -Clear filter currently applied to the package list -(@code{package-menu-clear-filter}). - @item H @kindex H @r{(Package Menu)} @findex package-menu-hide-package @@ -186,6 +165,48 @@ pressing @key{RET} to the prompt will hide the current package. @findex package-menu-toggle-hiding Toggle visibility of old versions of packages and also of versions from lower-priority archives (@code{package-menu-toggle-hiding}). + +@item / a +@kindex / a @r{(Package Menu)} +@findex package-menu-filter-by-archive +Filter package list by archive (@code{package-menu-filter-by-archive}). +This prompts for a package archive (e.g., @samp{gnu}), then shows only +packages from that archive. + +@item / k +@kindex / k @r{(Package Menu)} +@findex package-menu-filter-by-keyword +Filter package list by keyword (@code{package-menu-filter-by-keyword}). +This prompts for a keyword (e.g., @samp{games}), then shows only +packages with that keyword. + +@item / n +@kindex / n @r{(Package Menu)} +@findex package-menu-filter-by-name +Filter package list by name (@code{package-menu-filter-by-name}). +This prompts for a regular expression, then shows only packages +with names matching that regexp. + +@item / s +@kindex / s @r{(Package Menu)} +@findex package-menu-filter-by-status +Filter package list by status (@code{package-menu-filter-by-status}). +This prompts for one or more statuses (e.g., @samp{available}), then +shows only packages with matching status. + +@item / v +@kindex / v @r{(Package Menu)} +@findex package-menu-filter-by-version +Filter package list by version (@code{package-menu-filter-by-version}). +This prompts first for one of the qualifiers @samp{<}, @samp{>} or +@samp{=}, and then a package version, and shows packages that has a +lower, equal or higher version than the one specified. + +@item / / +@kindex / / @r{(Package Menu)} +@findex package-menu-filter-clear +Clear filter currently applied to the package list +(@code{package-menu-filter-clear}). @end table @noindent diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 9e23f055f53..9834952566f 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -929,7 +929,7 @@ GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT in the 1960s. It is somewhat inspired by Common Lisp, which became a standard in the 1980s. However, Emacs Lisp is much simpler than Common Lisp. (The standard Emacs distribution contains an optional extensions -file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) +file, @file{cl-lib.el}, that adds many Common Lisp features to Emacs Lisp.) @node Note for Novices @unnumberedsec A Note for Novices diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 8be8307c75f..cfef5c12d1e 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 diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index d855ecc0b96..caa08ffb1de 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -2192,10 +2192,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 @@ -2219,6 +2220,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 diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 325841d8f8a..442f6d156b6 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"); @@ -1442,6 +1447,54 @@ 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. +@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 +1594,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 +1796,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 +1825,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 +1890,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 +1926,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 +1948,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 +1973,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 @@ -2071,11 +2126,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/keymaps.texi b/doc/lispref/keymaps.texi index 259efea3248..4d513132e9f 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 58936686ad7..28942820793 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 1266cf8ef65..ac38b9d390d 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -646,6 +646,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 a8ddd45f891..f380f1669e0 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -2673,6 +2673,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 1c4e7e4d4e3..855dff2130a 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -2338,8 +2338,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 201ca18c1e4..a034ccdcd5c 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1689,7 +1689,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 diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 6970f718ee0..f515213615e 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -2426,18 +2426,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 diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index c9301c9d186..d0791d40196 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -5915,10 +5915,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 diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index f9196f808e7..1dab29b8a5a 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -35164,16 +35164,7 @@ which are called at various times. Calc defines a number of hooks that help you to customize it in various ways. Calc uses the Lisp function @code{run-hooks} to invoke the hooks shown below. Several other customization-related variables are also described here. - -@defvar calc-load-hook -This hook is called at the end of @file{calc.el}, after the file has -been loaded, before any functions in it have been called, but after -@code{calc-mode-map} and similar variables have been set up. -@end defvar - -@defvar calc-ext-load-hook -This hook is called at the end of @file{calc-ext.el}. -@end defvar +To run code after Calc has loaded, use @code{with-eval-after-load}. @defvar calc-start-hook This hook is called as the last step in a @kbd{M-x calc} command. diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index 5965da16bb7..d7497806602 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -185,13 +185,12 @@ In your @file{~/.emacs} file, or in the system-wide initialization file @file{default.el} in the @file{site-lisp} directory, put @example -(add-hook 'dired-load-hook - (lambda () - (load "dired-x") - ;; Set dired-x global variables here. For example: - ;; (setq dired-guess-shell-gnutar "gtar") - ;; (setq dired-x-hands-off-my-keys nil) - )) +(with-eval-after-load 'dired + (require 'dired-x) + ;; Set dired-x global variables here. For example: + ;; (setq dired-guess-shell-gnutar "gtar") + ;; (setq dired-x-hands-off-my-keys nil) + )) (add-hook 'dired-mode-hook (lambda () ;; Set dired-x buffer-local variables here. For example: @@ -242,12 +241,10 @@ If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over or call @code{dired-x-bind-find-file} after changing the value. @example -(add-hook 'dired-load-hook - (lambda () - ;; Bind dired-x-find-file. - (setq dired-x-hands-off-my-keys nil) - (load "dired-x") - )) +(with-eval-after-load 'dired + ;; Bind dired-x-find-file. + (setq dired-x-hands-off-my-keys nil) + (require 'dired-x)) @end example @node Omitting Files in Dired @@ -294,8 +291,8 @@ Marked files are never omitted. @end table @noindent -In order to make Dired Omit work you first need to load @file{dired-x.el} -inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate +In order to make Dired Omit work you need to load @file{dired-x} +after loading @file{dired} (@pxref{Installation}) and then evaluate @code{(dired-omit-mode 1)} in some way (@pxref{Omitting Variables}). @ifnottex @@ -410,7 +407,7 @@ The default value is @kbd{C-o}. @item @cindex RCS files, how to omit them in Dired @cindex omitting RCS files in Dired -If you wish to avoid seeing RCS files and the @file{RCS} directory, then put +If you wish to avoid seeing RCS files and the @file{RCS} directory, then use @example (setq dired-omit-files @@ -418,7 +415,7 @@ If you wish to avoid seeing RCS files and the @file{RCS} directory, then put @end example @noindent -in the @code{dired-load-hook} (@pxref{Installation}). This assumes +after loading @file{dired-x} (@pxref{Installation}). This assumes @code{dired-omit-localp} has its default value of @code{no-dir} to make the @code{^}-anchored matches work. As a slower alternative, with @code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of @@ -429,7 +426,7 @@ in the @code{dired-load-hook} (@pxref{Installation}). This assumes @cindex omitting tib files in Dired If you use @code{tib}, the bibliography program for use with @TeX{} and @LaTeX{}, and you -want to omit the @file{INDEX} and the @file{*-t.tex} files, then put +want to omit the @file{INDEX} and the @file{*-t.tex} files, then use @example (setq dired-omit-files @@ -437,13 +434,13 @@ want to omit the @file{INDEX} and the @file{*-t.tex} files, then put @end example @noindent -in the @code{dired-load-hook} (@pxref{Installation}). +after loading @file{dired-x} (@pxref{Installation}). @item @cindex dot files, how to omit them in Dired @cindex omitting dot files in Dired If you do not wish to see @samp{dot} files (files starting with a @file{.}), -then put +then use @example (setq dired-omit-files @@ -451,7 +448,7 @@ then put @end example @noindent -in the @code{dired-load-hook} (@pxref{Installation}). (Of course, a +after loading @file{dired-x} (@pxref{Installation}). (Of course, a better way to achieve this particular goal is simply to omit @samp{-a} from @code{dired-listing-switches}.) @@ -830,7 +827,7 @@ When installed @file{dired-x} will substitute @code{dired-x-find-file} for (normally bound to @kbd{C-x 4 C-f}). In order to use this feature, you will need to set -@code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook} +@code{dired-x-hands-off-my-keys} to @code{nil} before loading @file{dired-x} (@pxref{Optional Installation File At Point}). @table @code diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 99ba89b0d7f..1ef13716b11 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -1197,10 +1197,6 @@ refer to Emacs manual for the information on how to set Emacs X resources. The bulk of customization can be done via the following hooks: @table @code -@item ediff-load-hook -@vindex ediff-load-hook -This hook can be used to change defaults after Ediff is loaded. - @item ediff-before-setup-hook @vindex ediff-before-setup-hook Hook that is run just before Ediff rearranges windows to its liking. @@ -1211,8 +1207,8 @@ Can be used to save windows configuration. @vindex ediff-mode-map This hook can be used to alter bindings in Ediff's keymap, @code{ediff-mode-map}. These hooks are -run right after the default bindings are set but before -@code{ediff-load-hook}. The regular user needs not be concerned with this +run right after the default bindings are set. +The regular user needs not be concerned with this hook---it is provided for implementers of other Emacs packages built on top of Ediff. @@ -1545,12 +1541,13 @@ directly (using @kbd{j}) to any numbered difference. Users can supply their own functions to specify how Ediff should do -selective browsing. To change the default Ediff function, add a function to -@code{ediff-load-hook} which will do the following assignments: +selective browsing. To change the default Ediff function, use +something like the following: @example -(setq ediff-hide-regexp-matches-function 'your-hide-function) -(setq ediff-focus-on-regexp-matches-function 'your-focus-function) +(with-eval-after-load 'ediff + (setq ediff-hide-regexp-matches-function 'your-hide-function) + (setq ediff-focus-on-regexp-matches-function 'your-focus-function)) @end example @strong{Useful hint}: To specify a regexp that matches everything, don't @@ -1728,23 +1725,17 @@ difference region in buffer A (this face is not a good choice, by the way). If you are unhappy with just @emph{some} of the aspects of the default faces, you can modify them when Ediff is being loaded using -@code{ediff-load-hook}. For instance: +@code{with-eval-after-load}. For instance: @smallexample -(add-hook 'ediff-load-hook - (lambda () - (set-face-foreground - ediff-current-diff-face-B "blue") - (set-face-background - ediff-current-diff-face-B "red") - (make-face-italic - ediff-current-diff-face-B))) +(with-eval-after-load 'ediff + (set-face-foreground + ediff-current-diff-face-B "blue") + (set-face-background + ediff-current-diff-face-B "red") + (make-face-italic ediff-current-diff-face-B)) @end smallexample -@strong{Please note:} to set Ediff's faces, use only @code{copy-face} -or @code{set/make-face-@dots{}} as shown above. Emacs's low-level -face-manipulation functions should be avoided. - @node Narrowing @section Narrowing diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index 962f76d1796..50a208d233b 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -2515,9 +2515,8 @@ To avoid seeing backup files (and other ``uninteresting'' files) in Dired, load @code{dired-x} by adding the following to your @file{.emacs} file: @lisp -(add-hook 'dired-load-hook - (lambda () - (require 'dired-x))) +(with-eval-after-load 'dired + (require 'dired-x)) @end lisp With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer. diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi index 55320bf4c32..9a14a95f797 100644 --- a/doc/misc/gnus-coding.texi +++ b/doc/misc/gnus-coding.texi @@ -96,16 +96,6 @@ Read passwords from user, possibly using a password cache. @c As of 2005-10-21... There are no Gnus dependencies in this file. -@item tls.el -TLS/SSL support via wrapper around GnuTLS -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item pgg*.el -Glue for the various PGP implementations. -@c As of 2005-10-21... -There are no Gnus dependencies in these files. - @item sha1.el SHA1 Secure Hash Algorithm. @c As of 2007-08-25... diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index fbdf09420a9..b5eb81b787e 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -1563,12 +1563,6 @@ secondary select methods. @table @code -@item gnus-load-hook -@vindex gnus-load-hook -A hook run while Gnus is being loaded. Note that this hook will -normally be run just once in each Emacs session, no matter how many -times you start Gnus. - @item gnus-before-startup-hook @vindex gnus-before-startup-hook A hook called as the first thing when Gnus is started. @@ -27910,7 +27904,7 @@ The revised Gnus @acronym{FAQ} is included in the manual, @acronym{TLS} wrapper shipped with Gnus @acronym{TLS}/@acronym{SSL} is now supported in @acronym{IMAP} and -@acronym{NNTP} via @file{tls.el} and GnuTLS. +@acronym{NNTP} via GnuTLS. @item Improved anti-spam features. diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi index 547b16622fc..5cb6b19181c 100644 --- a/doc/misc/idlwave.texi +++ b/doc/misc/idlwave.texi @@ -1805,8 +1805,8 @@ Structure tag completion is not enabled by default. To enable it, simply add the following to your @file{.emacs}: @lisp - (add-hook 'idlwave-load-hook - (lambda () (require 'idlw-complete-structtag))) +(with-eval-after-load 'idlwave + (require 'idlw-complete-structtag)) @end lisp Once enabled, you'll also be able to access online help on the structure @@ -2360,10 +2360,6 @@ is first called. Normal hook. Executed when a buffer is put into @code{idlwave-mode}. @end defopt -@defopt idlwave-load-hook -Normal hook. Executed when @file{idlwave.el} is loaded. -@end defopt - @node The IDLWAVE Shell @chapter The IDLWAVE Shell @cindex IDLWAVE shell diff --git a/doc/misc/ido.texi b/doc/misc/ido.texi index 74d0bdd29fc..7cc4edd2865 100644 --- a/doc/misc/ido.texi +++ b/doc/misc/ido.texi @@ -590,7 +590,7 @@ Now you can customize @code{completion-ignored-extensions} as well. Go ahead and add all the useless object files, backup files, shared library files and other computing flotsam you don't want Ido to show. -@strong{Note:} Ido will still complete the ignored elements +@strong{Please note:} Ido will still complete the ignored elements if it would otherwise not show any other matches. So if you type out the name of an ignored file, Ido will still let you open it just fine. diff --git a/doc/misc/org.texi b/doc/misc/org.texi index 0de91fa803b..897979610ec 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -3979,10 +3979,9 @@ key bindings for this are really too long; you might want to bind this also to @kbd{M-n} and @kbd{M-p}. @lisp -(add-hook 'org-load-hook - (lambda () - (define-key org-mode-map "\M-n" 'org-next-link) - (define-key org-mode-map "\M-p" 'org-previous-link))) +(with-eval-after-load 'org + (define-key org-mode-map "\M-n" 'org-next-link) + (define-key org-mode-map "\M-p" 'org-previous-link)) @end lisp @end table diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi index 013c5639a1e..0dab5241517 100644 --- a/doc/misc/reftex.texi +++ b/doc/misc/reftex.texi @@ -2896,9 +2896,8 @@ default. If you want to have these key bindings available, set in your Note that this variable has to be set before @RefTeX{} is loaded to have an effect. -@vindex reftex-load-hook -Changing and adding to @RefTeX{}'s key bindings is best done in the hook -@code{reftex-load-hook}. For information on the keymaps +Changing and adding to @RefTeX{}'s key bindings is best done using +@code{with-eval-after-load}. For information on the keymaps which should be used to add keys, see @ref{Keymaps and Hooks}. @node Faces @@ -5320,10 +5319,6 @@ argument. The keymap for @RefTeX{} mode. @end deffn -@deffn {Normal Hook} reftex-load-hook -Normal hook which is being run when loading @file{reftex.el}. -@end deffn - @deffn {Normal Hook} reftex-mode-hook Normal hook which is being run when turning on @RefTeX{} mode. @end deffn diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index c02887d104a..d151cee02cc 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -1068,7 +1068,7 @@ You can integrate @semantic{} with the Speedbar. line to your init file: @example -(add-hook 'speedbar-load-hook (lambda () (require 'semantic/sb))) +(with-eval-after-load 'speedbar (require 'semantic/sb)) @end example @noindent diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index 99612d5c8fb..f29a5a82e86 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -295,26 +295,11 @@ encrypted connection if the server supports it. Other possible values are: @code{starttls} to insist on STARTTLS; @code{ssl} to use TLS/SSL; and @code{plain} for no encryption. -Use of any form of TLS/SSL requires support in Emacs. You can either -use the built-in support (in Emacs 24.1 and later), or the -@file{starttls.el} Lisp library. The built-in support uses the GnuTLS -@footnote{@url{https://www.gnu.org/software/gnutls/}} library. -If your Emacs has GnuTLS support built-in, the function +Use of any form of TLS/SSL requires support in Emacs. You can use the +built-in support for the GnuTLS +@footnote{@url{https://www.gnu.org/software/gnutls/}} library. If your +Emacs has GnuTLS support built-in, the function @code{gnutls-available-p} is defined and returns non-@code{nil}. -Otherwise, you must use the @file{starttls.el} library (see that file for -more information on customization options, etc.). The Lisp library -requires one of the following external tools to be installed: - -@enumerate -@item -The GnuTLS command line tool @samp{gnutls-cli}, which you can get from -@url{https://www.gnu.org/software/gnutls/}. This is the recommended -tool, mainly because it can verify server certificates. - -@item -The @samp{starttls} external program, which you can get from -@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}. -@end enumerate @cindex certificates @cindex keys diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index 57ad0220103..c9c3daf963b 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -828,9 +828,6 @@ Hooks run when speedbar visits a file in the selected frame. @cindex @code{speedbar-visiting-tag-hook} @item speedbar-visiting-tag-hook Hooks run when speedbar visits a tag in the selected frame. -@cindex @code{speedbar-load-hook} -@item speedbar-load-hook -Hooks run when speedbar is loaded. @cindex @code{speedbar-reconfigure-keymaps-hook} @item speedbar-reconfigure-keymaps-hook Hooks run when the keymaps are regenerated. Keymaps are reconfigured @@ -913,12 +910,11 @@ bindings: This function creates a special keymap for use in speedbar. @item -Call your install function, or assign it to a hook like this: +Call your install function, like this: @smallexample -(if (featurep 'speedbar) - (@var{name}-install-speedbar-variables) - (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables)) +(with-eval-after-load 'speedbar + (@var{name}-install-speedbar-variables)) @end smallexample @item diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 6d9d7113f77..1ea515b2ae4 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -5,7 +5,7 @@ % \def\texinfoversion{2019-09-24.13} % -% Copyright 1985--1986, 1988, 1990--2020 Free Software Foundation, Inc. +% Copyright 1985, 1986, 1988, 1990-2019 Free Software Foundation, Inc. % % This texinfo.tex file is free software: you can redistribute it and/or % modify it under the terms of the GNU General Public License as @@ -7690,7 +7690,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % If SUBTOPIC is present, precede it with a space, and call \doind. % (At some time during the 20th century, this made a two-level entry in an % index such as the operation index. Nobody seemed to notice the change in -% behavior though.) +% behaviour though.) \def\dosubind#1#2#3{% \def\thirdarg{#3}% \ifx\thirdarg\empty diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 49c32ac3f17..61cf373024f 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -46,7 +46,7 @@ copy and modify this GNU manual.'' @node Top, Overview, (dir), (dir) @top @value{tramp} @value{trampver} User Manual -This file documents @value{tramp} @value{trampver}, a remote file +This file documents @w{@value{tramp} @value{trampver}}, a remote file editing package for Emacs. @value{tramp} stands for ``Transparent Remote (file) Access, Multiple @@ -312,7 +312,7 @@ behind the scenes when you open a file with @value{tramp}. @cindex GNU ELPA @vindex tramp-version -@value{tramp} is included as part of Emacs (since Emacs 22.1). +@value{tramp} is included as part of Emacs (since @w{Emacs 22.1}). @value{tramp} is also freely packaged for download on the Internet at @uref{https://ftp.gnu.org/gnu/tramp/}. The version number of @@ -324,9 +324,9 @@ A @value{tramp} release, which is packaged with Emacs, could differ slightly from the corresponding standalone release. This is because it isn't always possible to synchronize release dates between Emacs and @value{tramp}. Such version numbers have the Emacs version number -as suffix, like ``2.3.5.26.3''. This means @value{tramp} 2.3.5 as -integrated in Emacs 26.3. A complete list of @value{tramp} versions -packaged with Emacs can be retrieved by +as suffix, like ``2.3.5.26.3''. This means @w{@value{tramp} 2.3.5} as +integrated in @w{Emacs 26.3}. A complete list of @value{tramp} +versions packaged with Emacs can be retrieved by @vindex customize-package-emacs-version-alist @lisp @@ -557,13 +557,16 @@ of the local file name is the share exported by the remote host, @cindex method @option{davs} @cindex @option{dav} method @cindex @option{davs} method +@cindex method @option{media} +@cindex @option{media} method On systems, which have installed @acronym{GVFS, the GNOME Virtual File System}, its offered methods could be used by @value{tramp}. Examples are @file{@trampfn{sftp,user@@host,/path/to/file}}, @file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP -file system), @file{@trampfn{dav,user@@host,/path/to/file}} and -@file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares). +file system), @file{@trampfn{dav,user@@host,/path/to/file}}, +@file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares) and +@file{@trampfn{media,device,/path/to/file}} (for media devices). @anchor{Quick Start Guide: GNOME Online Accounts based methods} @@ -1126,7 +1129,8 @@ Emacs. @value{tramp} does not require a host name part of the remote file name when a single Android device is connected to @command{adb}. @value{tramp} instead uses @file{@trampfn{adb,,}} as the default name. -@command{adb devices} shows available host names. +@command{adb devices}, run in a shell outside Emacs, shows available +host names. @option{adb} method normally does not need user name to authenticate on the Android device because it runs under the @command{adbd} @@ -1227,6 +1231,7 @@ supported by these methods. See method @option{nextcloud} for handling them. @item @option{gdrive} +@cindex @acronym{GNOME} Online Accounts @cindex method @option{gdrive} @cindex @option{gdrive} method @cindex google drive @@ -1242,8 +1247,26 @@ Since Google Drive uses cryptic blob file names internally, could produce unexpected behavior in case two files in the same directory have the same @code{display-name}, such a situation must be avoided. +@item @option{media} +@cindex method @option{media} +@cindex @option{media} method +@cindex media + +Media devices, like cell phones, tablets, cameras, can be accessed via +the @option{media} method. Just the device name is needed in order to +specify the host in the file name. However, the device must already +be connected via USB, before accessing it. Possible device names are +visible via host name completion, @ref{File name completion}. + +Depending on the device type, the access could be read-only. Some +devices are accessible under different names in parallel, offering +different parts of their file system. + +@value{tramp} does not require a host name as part of the remote file +name when a single media device is connected. @value{tramp} instead +uses @file{@trampfn{media,,}} as the default name. + @item @option{nextcloud} -@cindex @acronym{GNOME} Online Accounts @cindex method @option{nextcloud} @cindex @option{nextcloud} method @cindex nextcloud @@ -1267,11 +1290,11 @@ that for security reasons refuse @command{ssh} connections. @defopt tramp-gvfs-methods This user option is a list of external methods for @acronym{GVFS}@. By default, this list includes @option{afp}, @option{dav}, -@option{davs}, @option{gdrive}, @option{nextcloud} and @option{sftp}. -Other methods to include are @option{ftp}, @option{http}, -@option{https} and @option{smb}. These methods are not intended to be -used directly as @acronym{GVFS}-based method. Instead, they are added -here for the benefit of @ref{Archive file names}. +@option{davs}, @option{gdrive}, @option{media}, @option{nextcloud} and +@option{sftp}. Other methods to include are @option{ftp}, +@option{http}, @option{https} and @option{smb}. These methods are not +intended to be used directly as @acronym{GVFS}-based method. Instead, +they are added here for the benefit of @ref{Archive file names}. If you want to use @acronym{GVFS}-based @option{ftp} or @option{smb} methods, you must add them to @code{tramp-gvfs-methods}, and you must @@ -1642,7 +1665,7 @@ suitable settings. Refer to the Lisp documentation of that variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. In the ELPA archives, there are several examples of such extensions. -They can be installed with Emacs' Package Manager. This includes +They can be installed with Emacs's Package Manager. This includes @table @samp @c @item anything-tramp @@ -2095,8 +2118,8 @@ preserves the path value, which can be used to update shell supports the login argument @samp{-l}. @end defopt -Starting with Emacs 26, @code{tramp-remote-path} can be set per host -via connection-local +Starting with @w{Emacs 26}, @code{tramp-remote-path} can be set per +host via connection-local @ifinfo variables, @xref{Connection Variables, , , emacs}. @end ifinfo @@ -2450,7 +2473,7 @@ where @samp{192.168.0.1} is the remote host IP address Android devices provide a restricted shell access through an USB connection. The local host must have the @command{adb} program installed. Usually, it is sufficient to open the file -@file{@trampfn{adb,,/}}. Then you can navigate in the filesystem via +@file{@trampfn{adb,,/}}. Then you can navigate in the file system via @code{dired}. Alternatively, applications such as @code{Termux} or @code{SSHDroid} @@ -2937,10 +2960,10 @@ Example: @end example During file name completion, remote directory contents are re-read -regularly to account for any changes in the filesystem that may affect -the completion candidates. Such re-reads can account for changes to -the file system by applications outside Emacs (@pxref{Connection -caching}). +regularly to account for any changes in the file system that may +affect the completion candidates. Such re-reads can account for +changes to the file system by applications outside Emacs +(@pxref{Connection caching}). @defopt tramp-completion-reread-directory-timeout The timeout is number of seconds since last remote command for @@ -3161,8 +3184,8 @@ ensures the correct name of the remote shell program. When @code{explicit-shell-file-name} is equal to @code{nil}, calling @code{shell} interactively will prompt for a shell name. -Starting with Emacs 26, you could use connection-local variables for -setting different values of @code{explicit-shell-file-name} for +Starting with @w{Emacs 26}, you could use connection-local variables +for setting different values of @code{explicit-shell-file-name} for different remote hosts. @ifinfo @xref{Connection Variables, , , emacs}. @@ -3231,7 +3254,7 @@ variables. @vindex async-shell-command-width @vindex COLUMNS@r{, environment variable} If Emacs supports the variable @code{async-shell-command-width} (since -Emacs 27.1), @value{tramp} cares about its value for asynchronous +@w{Emacs 27.1}), @value{tramp} cares about its value for asynchronous shell commands. It specifies the number of display columns for command output. For synchronous shell commands, a similar effect can be achieved by adding the environment variable @env{COLUMNS} to @@ -3844,8 +3867,8 @@ Where is the latest @value{tramp}? @item Which systems does it work on? -The package works successfully on Emacs 24, Emacs 25, Emacs 26, and -Emacs 27. +The package works successfully on @w{Emacs 25}, @w{Emacs 26}, @w{Emacs +27}, and @w{Emacs 28}. While Unix and Unix-like systems are the primary remote targets, @value{tramp} has equal success connecting to other platforms, such as @@ -4182,7 +4205,7 @@ Host indication in the mode line? @cindex @value{tramp} theme @vindex tramp-theme-face-remapping-alist -Install @file{tramp-theme} from GNU ELPA via Emacs' Package Manager. +Install @file{tramp-theme} from GNU ELPA via Emacs's Package Manager. Enable it via @kbd{M-x load-theme @key{RET} tramp @key{RET}}. Further customization is explained in user option @code{tramp-theme-face-remapping-alist}. diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index 478ec7037a8..aabb2f8acc3 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -8,9 +8,9 @@ @c In the Tramp GIT, the version numbers are auto-frobbed from @c tramp.el, and the bug report address is auto-frobbed from @c configure.ac. -@set trampver 2.4.3.27.1 +@set trampver 2.5.0-pre @set tramp-bug-report-address tramp-devel@@gnu.org -@set emacsver 24.4 +@set emacsver 25.1 @c Other flags from configuration. @set instprefix /usr/local diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi index 9ce809e7d4d..661eb7c947a 100644 --- a/doc/misc/viper.texi +++ b/doc/misc/viper.texi @@ -1752,10 +1752,10 @@ state. If @code{nil}, the cursor stays where it was before the switch. @item viper-always t @code{t} means: leave it to Viper to decide when a buffer must be brought up in Vi state, -Insert state, or Emacs state. This heuristics works well in virtually all -cases. @code{nil} means you either has to invoke @code{viper-mode} manually +Insert state, or Emacs state. This heuristic works well in virtually all +cases. @code{nil} means you either have to invoke @code{viper-mode} manually for each buffer (or you can add @code{viper-mode} to the appropriate major mode -hooks using @code{viper-load-hook}). +hooks using @code{with-eval-after-load}). This option must be set in your Viper customization file. @item viper-custom-file-name "~/.emacs.d/viper" @@ -1903,9 +1903,6 @@ List of (parameterless) functions called just after entering Replace state @item viper-emacs-state-hook nil List of (parameterless) functions called just after switching from Vi state to Emacs state. -@item viper-load-hook nil -List of (parameterless) functions called just after loading Viper. This is -the last chance to do customization before Viper is up and running. @end table @noindent You can reset some of these constants in Viper with the Ex command @kbd{:set} |