summaryrefslogtreecommitdiff
path: root/doc/misc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/misc')
-rw-r--r--doc/misc/auth.texi5
-rw-r--r--doc/misc/calc.texi11
-rw-r--r--doc/misc/cc-mode.texi79
-rw-r--r--doc/misc/dbus.texi75
-rw-r--r--doc/misc/dired-x.texi41
-rw-r--r--doc/misc/ediff.texi37
-rw-r--r--doc/misc/efaq.texi16
-rw-r--r--doc/misc/eieio.texi32
-rw-r--r--doc/misc/emacs-gnutls.texi2
-rw-r--r--doc/misc/emacs-mime.texi22
-rw-r--r--doc/misc/eshell.texi3
-rw-r--r--doc/misc/eudc.texi48
-rw-r--r--doc/misc/eww.texi28
-rw-r--r--doc/misc/gnus-coding.texi10
-rw-r--r--doc/misc/gnus.texi537
-rw-r--r--doc/misc/idlwave.texi8
-rw-r--r--doc/misc/ido.texi2
-rw-r--r--doc/misc/message.texi67
-rw-r--r--doc/misc/org.texi7
-rw-r--r--doc/misc/reftex.texi9
-rw-r--r--doc/misc/sem-user.texi2
-rw-r--r--doc/misc/smtpmail.texi33
-rw-r--r--doc/misc/speedbar.texi10
-rw-r--r--doc/misc/texinfo.tex419
-rw-r--r--doc/misc/tramp.texi310
-rw-r--r--doc/misc/trampver.texi5
-rw-r--r--doc/misc/url.texi2
-rw-r--r--doc/misc/viper.texi9
28 files changed, 1330 insertions, 499 deletions
diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index 61dc62e7711..f8fcb642901 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -227,6 +227,11 @@ machine YOURMACHINE login YOU password SMTPPASSWORD port 433
machine YOURMACHINE login YOU password GENERALPASSWORD
@end example
+If you wish to specify a particular SMTP authentication method to use
+with a machine, you can use the @code{smtp-auth} keyword.
+@xref{Authentication,, Authentication, smtpmail, Emacs SMTP Library},
+for available methods.
+
For url-auth authentication (HTTP/HTTPS), you need to put this in your
netrc file:
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/cc-mode.texi b/doc/misc/cc-mode.texi
index 544ff853351..adc233d99dd 100644
--- a/doc/misc/cc-mode.texi
+++ b/doc/misc/cc-mode.texi
@@ -350,11 +350,12 @@ Line-Up Functions
* Misc Line-Up::
-Customizing Macros
+Custom Macros
* Macro Backslashes::
* Macros with ;::
* Noise Macros::
+* Indenting Directives::
@end detailmenu
@end menu
@@ -1023,9 +1024,7 @@ These key sequences are not bound in AWK Mode, which doesn't have
preprocessor statements.
@item @kbd{M-x c-backward-into-nomenclature}
-@itemx @kbd{M-x c-forward-into-nomenclature}
@findex c-backward-into-nomenclature
-@findex c-forward-into-nomenclature
@findex backward-into-nomenclature @r{(c-)}
@findex forward-into-nomenclature @r{(c-)}
A popular programming style, especially for object-oriented languages
@@ -2131,6 +2130,11 @@ For Pike autodoc markup, the standard in Pike.
@item gtkdoc
@cindex GtkDoc markup
For GtkDoc markup, widely used in the Gnome community.
+
+@item doxygen
+@cindex Doxygen markup
+For Doxygen markup, which can be used with C, C++, Java and variety of
+other languages.
@end table
The above is by no means complete. If you'd like to see support for
@@ -6389,6 +6393,26 @@ function is the same as specifying a list @code{(c-lineup-assignments
@comment ------------------------------------------------------------
+@defun c-lineup-ternary-bodies
+@findex lineup-ternary-bodies @r{(c-)}
+Line up true and false branches of a ternary operator
+(i.e. @code{?:}). More precisely, if the line starts with a colon
+which is a part of a said operator, align it with corresponding
+question mark. For example:
+
+@example
+@group
+return arg % 2 == 0 ? arg / 2
+ : (3 * arg + 1); @hereFn{c-lineup-ternary-bodies}
+@end group
+@end example
+
+@workswith @code{arglist-cont}, @code{arglist-cont-nonempty} and
+@code{statement-cont}.
+@end defun
+
+@comment ------------------------------------------------------------
+
@defun c-lineup-cascaded-calls
@findex lineup-cascaded-calls @r{(c-)}
Line up ``cascaded calls'' under each other. If the line begins with
@@ -6949,6 +6973,10 @@ is @code{nil}, all lines inside macro definitions are analyzed as
@code{cpp-macro-cont}.
@end defopt
+Sometimes you may want to indent particular directives
+(e.g. @code{#pragma}) as though they were statements. To do this, see
+@ref{Indenting Directives}.
+
Because a macro can expand into anything at all, near where one is
invoked @ccmode{} can only indent and fontify code heuristically.
Sometimes it gets it wrong. Usually you should try to design your
@@ -6965,6 +6993,7 @@ Macros}.
* Macro Backslashes::
* Macros with ;::
* Noise Macros::
+* Indenting Directives::
@end menu
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@@ -7074,7 +7103,7 @@ initialization code, after the mode hooks have run.
@end defun
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Noise Macros, , Macros with ;, Custom Macros
+@node Noise Macros, Indenting Directives, Macros with ;, Custom Macros
@comment node-name, next, previous, up
@section Noise Macros
@cindex noise macros
@@ -7131,6 +7160,48 @@ after the mode hooks have run.
@end defun
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Indenting Directives, , Noise Macros, Custom Macros
+@comment node-name, next, previous, up
+@section Indenting Directives
+@cindex Indenting Directives
+@cindex Indenting #pragma
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Sometimes you may want to indent particular preprocessor directives
+(e.g. @code{#pragma}) as though they were statements. To do this,
+first set up @code{c-cpp-indent-to-body-directives} to include the
+directive name(s), then enable the ``indent to body'' feature with
+@code{c-toggle-cpp-indent-to-body}.
+
+@defopt c-cpp-indent-to-body-directives
+@vindex cpp-indent-to-body-directives (c-)
+This variable is a list of names of CPP directives (not including the
+introducing @samp{#}) which will be indented as though statements.
+Each element is a string, and must be a valid identifier. The default
+value is @code{("pragma")}.
+
+If you add more directives to this variable, or remove directives from
+it, whilst ``indent to body'' is active, you need to re-enable the
+feature by calling @code{c-toggle-cpp-indent-to-body} for these
+changes to take effect@footnote{Note that the removal of directives
+doesn't work satisfactorally on XEmacs or on very old versions of
+Emacs}.
+@end defopt
+
+@defun c-toggle-cpp-indent-to-body
+@findex toggle-cpp-indent-to-body (c-)
+With @kbd{M-x c-toggle-cpp-indent-to-body}, you enable or disable the
+``indent to body'' feature. When called programmatically, it takes an
+optional numerical argument. A positive value will enable the
+feature, a zero or negative value will disable it.
+
+You should set up @code{c-cpp-indent-to-body-directives} before
+calling this function, since the function sets internal state which
+depends on that variable.
+@end defun
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Odds and Ends, Sample Init File, Custom Macros, Top
@comment node-name, next, previous, up
@chapter Odds and Ends
diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 167d2bd5ac1..2880b7f7430 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -59,7 +59,7 @@ another. An overview of D-Bus can be found at
* Type Conversion:: Mapping Lisp types and D-Bus types.
* Synchronous Methods:: Calling methods in a blocking way.
* Asynchronous Methods:: Calling methods non-blocking.
-* Receiving Method Calls:: Offering own methods.
+* Register Objects:: Offering own services.
* Signals:: Sending and receiving signals.
* Alternative Buses:: Alternative buses and environments.
* Errors and Events:: Errors and events.
@@ -744,16 +744,17 @@ result can be any valid D-Bus value, or @code{nil} if there is no
@end lisp
@end defun
-@defun dbus-set-property bus service path interface property value
+@defun dbus-set-property bus service path interface property [type] value
This function sets the value of @var{property} of @var{interface} to
@var{value}. It will be checked at @var{bus}, @var{service},
-@var{path}. When the value is successfully set, this function returns
-@var{value}. Otherwise, it returns @code{nil}. Example:
+@var{path}. @var{value} can be preceded by a @var{type} symbol. When
+the value is successfully set, this function returns @var{value}.
+Otherwise, it returns @code{nil}. Example:
@lisp
(dbus-set-property
:session "org.kde.kaccess" "/MainApplication"
- "com.trolltech.Qt.QApplication" "doubleClickInterval" 500)
+ "com.trolltech.Qt.QApplication" "doubleClickInterval" :uint16 500)
@result{} 500
@end lisp
@@ -1340,11 +1341,15 @@ message arrives, and @var{handler} is called. Example:
@end defun
-@node Receiving Method Calls
-@chapter Offering own methods.
+@node Register Objects
+@chapter Offering own services.
@cindex method calls, returning
@cindex returning method calls
+You can offer an own service in D-Bus, which will be visible by other
+D-Bus clients. See @uref{https://dbus.freedesktop.org/doc/dbus-api-design.html}
+for a discussion of the design.
+
In order to register methods on the D-Bus, Emacs has to request a well
known name on the D-Bus under which it will be available for other
clients. Names on the D-Bus can be registered and unregistered using
@@ -1462,7 +1467,15 @@ cons cell, @var{handler} can return this object directly, instead of
returning a list containing the object.
If @var{handler} returns a reply message with an empty argument list,
-@var{handler} must return the symbol @code{:ignore}.
+@var{handler} must return the symbol @code{:ignore} in order
+to distinguish it from @code{nil} (the boolean false).
+
+If @var{handler} detects an error, it shall return the list
+@code{(:error @var{error-name} @var{error-message)}}.
+@var{error-name} is a namespaced string which characterizes the error
+type, and @var{error-message} is a free text string. Alternatively,
+any Emacs signal @code{dbus-error} in @var{handler} raises a D-Bus
+error message with the error name @samp{org.freedesktop.DBus.Error.Failed}.
When @var{dont-register-service} is non-@code{nil}, the known name
@var{service} is not registered. This means that other D-Bus clients
@@ -1512,17 +1525,20 @@ could use the command line tool @code{dbus-send} in a shell:
boolean true
@end example
-You can indicate an error by raising the Emacs signal
-@code{dbus-error}. The handler above could be changed like this:
+You can indicate an error by returning an @code{:error} list reply, or
+by raising the Emacs signal @code{dbus-error}. The handler above
+could be changed like this:
@lisp
(defun my-dbus-method-handler (&rest args)
- (unless (and (= (length args) 1) (stringp (car args)))
- (signal 'dbus-error (list (format "Wrong argument list: %S" args))))
- (condition-case err
- (find-file (car args))
- (error (signal 'dbus-error (cdr err))))
- t)
+ (if (not (and (= (length args) 1) (stringp (car args))))
+ (list :error
+ "org.freedesktop.TextEditor.Error.InvalidArgs"
+ (format "Wrong argument list: %S" args))
+ (condition-case err
+ (find-file (car args))
+ (error (signal 'dbus-error (cdr err))))
+ t))
@end lisp
The test then runs
@@ -1534,12 +1550,23 @@ The test then runs
"org.freedesktop.TextEditor.OpenFile" \
string:"/etc/hosts" string:"/etc/passwd"
-@print{} Error org.freedesktop.DBus.Error.Failed:
+@print{} Error org.freedesktop.TextEditor.Error.InvalidArgs:
Wrong argument list: ("/etc/hosts" "/etc/passwd")
@end example
+
+@example
+# dbus-send --session --print-reply \
+ --dest="org.freedesktop.TextEditor" \
+ "/org/freedesktop/TextEditor" \
+ "org.freedesktop.TextEditor.OpenFile" \
+ string:"/etc/crypttab"
+
+@print{} Error org.freedesktop.DBus.Error.Failed:
+ D-Bus error: "File is not readable", "/etc/crypttab"
+@end example
@end defun
-@defun dbus-register-property bus service path interface property access value &optional emits-signal dont-register-service
+@defun dbus-register-property bus service path interface property access [type] value &optional emits-signal dont-register-service
With this function, an application declares a @var{property} on the D-Bus
@var{bus}.
@@ -1556,14 +1583,18 @@ discussion of @var{dont-register-service} below).
@var{property} is the name of the property of @var{interface}.
@var{access} indicates, whether the property can be changed by other
-services via D-Bus. It must be either the symbol @code{:read} or
-@code{:readwrite}. @var{value} is the initial value of the property,
-it can be of any valid type (@xref{dbus-call-method}, for details).
+services via D-Bus. It must be either the symbol @code{:read},
+@code{:write} or @code{:readwrite}.
+
+@var{value} is the initial value of the property, it can be of any
+valid type (@xref{dbus-call-method}, for details). @var{value} can be
+preceded by a @var{type} symbol.
If @var{property} already exists on @var{path}, it will be
overwritten. For properties with access type @code{:read} this is the
only way to change their values. Properties with access type
-@code{:readwrite} can be changed by @code{dbus-set-property}.
+@code{:write} or @code{:readwrite} can be changed by
+@code{dbus-set-property}.
The interface @samp{org.freedesktop.DBus.Properties} is added to
@var{path}, including a default handler for the @samp{Get},
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 f948a489f44..3c1244101f4 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -1595,6 +1595,10 @@ xterm-direct2 xterm with direct-color indexing (old)
xterm-direct xterm with direct-color indexing
@end example
+If Terminfo database is not available, but 24-bit direct color mode is
+supported, it can still be enabled by defining the environment
+variable @env{COLORTERM} to @samp{truecolor}.
+
Terminals with @samp{RGB} capability treat pixels #000001 - #000007 as
indexed colors to maintain backward compatibility with applications
that are unaware of direct color mode. Therefore the seven darkest
@@ -2515,9 +2519,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.
@@ -3461,7 +3464,6 @@ see @ref{Packages that do not come with Emacs}.
@cindex Finding other packages
@cindex Lisp packages that do not come with Emacs
@cindex Packages, those that do not come with Emacs
-@cindex Emacs Lisp List
@cindex Emacs Lisp Archive
The easiest way to add more features to your Emacs is to use the
@@ -3497,10 +3499,6 @@ The @uref{https://emacswiki.org, Emacs Wiki} contains pointers to some
additional extensions. @uref{https://wikemacs.org, WikEmacs} is an
alternative wiki for Emacs.
-@uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html, The Emacs
-Lisp List (ELL)}, has pointers to many Emacs Lisp files, but at time
-of writing it is no longer being updated.
-
It is impossible for us to list here all the sites that offer Emacs
Lisp packages. If you are interested in a specific feature, then
after checking Emacs itself and GNU ELPA, a web search is often the
@@ -4189,7 +4187,7 @@ You can get the old behavior by binding @kbd{SPC} to
(define-key minibuffer-local-filename-completion-map (kbd "SPC")
'minibuffer-complete-word)
-(define-key minibuffer-local-must-match-filename-map (kbd "SPC")
+(define-key minibuffer-local-filename-must-match-map (kbd "SPC")
'minibuffer-complete-word)
@end lisp
diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi
index aceaff051e3..8dd394cb848 100644
--- a/doc/misc/eieio.texi
+++ b/doc/misc/eieio.texi
@@ -698,6 +698,27 @@ and argument-order conventions are similar to those used for
referencing vectors (@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference
Manual}).
+@defmac oref obj slot
+@anchor{oref}
+This macro retrieves the value stored in @var{obj} in the named
+@var{slot}. Slot names are determined by @code{defclass} which
+creates the slot.
+
+This is a generalized variable that can be used with @code{setf} to
+modify the value stored in @var{slot}. @xref{Generalized
+Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
+@end defmac
+
+@defmac oref-default class slot
+@anchor{oref-default}
+This macro returns the value of the class-allocated @var{slot} from
+@var{class}.
+
+This is a generalized variable that can be used with @code{setf} to
+modify the value stored in @var{slot}. @xref{Generalized
+Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
+@end defmac
+
@defmac oset object slot value
This macro sets the value behind @var{slot} to @var{value} in
@var{object}. It returns @var{value}.
@@ -716,17 +737,6 @@ changed, this can be arranged by simply executing this bit of code:
@end example
@end defmac
-@defmac oref obj slot
-@anchor{oref}
-Retrieve the value stored in @var{obj} in the slot named by @var{slot}.
-Slot is the name of the slot when created by @dfn{defclass}.
-@end defmac
-
-@defmac oref-default class slot
-@anchor{oref-default}
-Get the value of the class-allocated @var{slot} from @var{class}.
-@end defmac
-
The following accessors are defined by CLOS to reference or modify
slot values, and use the previously mentioned set/ref routines.
diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi
index 7c57cc032c7..bb13ebdf238 100644
--- a/doc/misc/emacs-gnutls.texi
+++ b/doc/misc/emacs-gnutls.texi
@@ -190,7 +190,7 @@ the connection process.
The optional @var{parameters} argument is a list of keywords and
values. The only keywords which currently have any effect are
-@code{:client-certificate} and @code{:nowait}.
+@code{:client-certificate}, @code{:nowait}, and @code{:coding}.
Passing @w{@code{:client certificate t}} triggers looking up of client
certificates matching @var{host} and @var{service} using the
diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi
index 42a7750b9ac..9180b4ec205 100644
--- a/doc/misc/emacs-mime.texi
+++ b/doc/misc/emacs-mime.texi
@@ -472,6 +472,13 @@ the case if you save it to disk and launch it in a different way
to launch any external programs, set this variable to @code{nil} or
@code{ask}.
+@item mm-inline-font-lock
+@vindex mm-inline-font-lock
+If non-@code{nil}, inlined parts that support font locking (for
+instance, patches or code snippets) will be font-locked. This may be
+overriden by callers that have their own ways of enabling/inhibiting
+font locking.
+
@end table
@node Files and Directories
@@ -686,8 +693,17 @@ Valid values are @samp{inline} and @samp{attachment}
@item encoding
Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
-@samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset
-Translation}.
+@samp{base64}. @xref{Charset
+Translation}. This parameter says what
+@code{Content-Transfer-Encoding} to use when sending the part, and is
+normally computed automatically.
+
+@item data-encoding
+This parameter says what encoding has been used on the data, and the
+data will be decoded before use. Valid values are
+@samp{quoted-printable} and @samp{base64}. This is useful when you
+have a part with binary data (for instance an image) inserted directly
+into the Message buffer inside the @samp{"<#part>...<#/part>"} tags.
@item description
A description of the part (@code{Content-Description}).
@@ -917,7 +933,7 @@ Here's an example:
@lisp
(add-to-list 'gnus-newsgroup-variables 'mm-coding-system-priorities)
(setq gnus-parameters
- (nconc
+ (append
;; Some charsets are just examples!
'(("^cn\\." ;; Chinese
(mm-coding-system-priorities
diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 57f713635f8..c33ca0ea02c 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -159,6 +159,9 @@ The following persons have made contributions to Eshell.
@itemize @bullet
@item
+John Wiegley is the original author of Eshell.
+
+@item
Eli Zaretskii made it possible for Eshell to run without requiring
asynchronous subprocess support. This is important for MS-DOS, which
does not have such support.
diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi
index 701340ed6e2..69a8512f175 100644
--- a/doc/misc/eudc.texi
+++ b/doc/misc/eudc.texi
@@ -83,6 +83,8 @@ Currently supported back-ends are:
LDAP, Lightweight Directory Access Protocol
@item
BBDB, Big Brother's Insidious Database
+@item
+macOS Contacts
@end itemize
The main features of the EUDC interface are:
@@ -107,6 +109,7 @@ Interface to BBDB to let you insert server records into your own BBDB database
@menu
* LDAP:: What is LDAP ?
* BBDB:: What is BBDB ?
+* macOS Contacts:: What is macOS Contacts ?
@end menu
@@ -159,6 +162,17 @@ queries on multiple servers.
EUDC also offers a means to insert results from directory queries into
your own local BBDB (@pxref{Creating BBDB Records})
+
+@node macOS Contacts
+@section macOS Contacts
+
+This EUDC back end considers macOS Contacts as a directory server just
+like LDAP, though the macOS Contacts application always runs locally
+on your machine. The Contacts application was previously called
+Address Book; the EUDC macOS Contacts back end also works on those
+older versions.
+
+
@node Installation
@chapter Installation
@@ -185,6 +199,7 @@ email composition buffers (@pxref{Inline Query Expansion})
@menu
* LDAP Configuration:: EUDC needs external support for LDAP
+* macOS Contacts Configuration:: Enable the macOS Contacts backend
@end menu
@node LDAP Configuration
@@ -379,6 +394,39 @@ The @command{ldapsearch} command is formatted such that it can be
copied and pasted into a terminal. Set the @command{ldapsearch} debug
level to 5 by appending @code{-d 5} to the command line.
+
+@node macOS Contacts Configuration
+@section macOS Contacts Configuration
+
+macOS Contacts support is added by means of @file{eudcb-mab.el}, or
+@file{eudcb-macos-contacts.el} which are part of Emacs.
+
+To enable a macOS Contacts backend, first `require' the respective
+library to load it, and then set the `eudc-server' to localhost in
+your init file:
+@lisp
+(require 'eudcb-macos-contacts)
+(eudc-macos-contacts-set-server "localhost")
+@end lisp
+
+@file{eudcb-macos-contacts.el} uses the public scripting interfaces
+offered by the Contacts app via the macOS Open Scripting Architecture
+(OSA). To accomplish this, @file{eudcb-macos-contacts.el} uses an
+external command line utility named osascript, which is included with
+all macOS versions since 10.0 (which was released 2001).
+@file{eudcb-macos-contacts.el} is hence recommended for all new
+configurations.
+
+@file{eudcb-mab.el} reverse engineers the format of the database file
+used by the macOS Contacts app, and accesses its contents directly.
+While this may promise some performance advantages, it comes at the
+cost of using an undocumented interface. Hence, users of
+@file{eudcb-mab.el} are recommended to double check the compatibility
+of @file{eudcb-mab.el} before upgrading to a new version of macOS.
+@file{eudcb-mab.el} is retained for backwards compatibility with
+existing configurations, and may be removed in a future release.
+
+
@node Usage
@chapter Usage
diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi
index e3191cbe48a..85be112402c 100644
--- a/doc/misc/eww.texi
+++ b/doc/misc/eww.texi
@@ -52,6 +52,7 @@ modify this GNU manual.''
* Overview::
* Basics::
* Advanced::
+* Command Line::
Appendices
* History and Acknowledgments::
@@ -135,7 +136,9 @@ HTML-specified colors or not. This sets the @code{shr-use-colors} variable.
A URL can be downloaded with @kbd{d} (@code{eww-download}). This
will download the link under point if there is one, or else the URL of
the current page. The file will be written to the directory specified
-in @code{eww-download-directory} (default: @file{~/Downloads/}).
+by @code{eww-download-directory} (default: @file{~/Downloads/}, if it
+exists; otherwise as specified by the @samp{DOWNLOAD} @acronym{XDG}
+directory)).
@findex eww-back-url
@findex eww-forward-url
@@ -283,6 +286,14 @@ contrast. If that is still too low for you, you can customize the
variables @code{shr-color-visible-distance-min} and
@code{shr-color-visible-luminance-min} to get a better contrast.
+@vindex shr-max-width
+@vindex shr-width
+ By default, the max width used when rendering is 120 characters, but
+this can be adjusted by changing the @code{shr-max-width} variable.
+If a specified width is preferred no matter what the width of the
+window is, @code{shr-width} can be set. If both variables are
+@code{nil}, the window width will always be used.
+
@vindex shr-discard-aria-hidden
@cindex @code{aria-hidden}, HTML attribute
The HTML attribute @code{aria-hidden} is meant to tell screen
@@ -327,6 +338,21 @@ thus allowing for the use of the usual substitutions, such as
@code{\[eww-reload]} for the current key binding of the
@code{eww-reload} command.
+@node Command Line
+@chapter Command Line Usage
+
+It can be convenient to start eww directly from the command line. The
+@code{eww-browse} function can be used for that:
+
+@example
+emacs -f eww-browse https://gnu.org
+@end example
+
+This also allows registering Emacs as a @acronym{MIME} handler for the
+@samp{"text/x-uri"} media type. How to do that varies between
+systems, but typically you'd register the handler to call @samp{"emacs
+-f eww-browse %u"}.
+
@node History and Acknowledgments
@appendix History and Acknowledgments
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 a96be30cd61..4a09eacdf15 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -402,6 +402,7 @@ This manual corresponds to Gnus v5.13
@end iftex
@menu
+* Don't Panic:: Your first 20 minutes with Gnus.
* Starting Up:: Finding news can be a pain.
* Group Buffer:: Selecting, subscribing and killing groups.
* Summary Buffer:: Reading, saving and posting articles.
@@ -436,7 +437,7 @@ Starting Gnus
* Finding the News:: Choosing a method for getting news.
* The Server is Down:: How can I read my mail then?
-* Slave Gnusae:: You can have more than one Gnus active at a time.
+* Child Gnusae:: You can have more than one Gnus active at a time.
* Fetching a Group:: Starting Gnus just to read a group.
* New Groups:: What is Gnus supposed to do with new groups?
* Changing Servers:: You may want to move from one server to another.
@@ -640,7 +641,7 @@ Select Methods
* Getting Mail:: Reading your personal mail with Gnus.
* Browsing the Web:: Getting messages from a plethora of Web sources.
* Other Sources:: Reading directories, files.
-* Combined Groups:: Combining groups into one group.
+* Virtual Groups:: Combining articles from multiple sources.
* Email Based Diary:: Using mails to manage diary events in Gnus.
* Gnus Unplugged:: Reading news and mail offline.
@@ -715,9 +716,10 @@ Document Groups
* Document Server Internals:: How to add your own document types.
-Combined Groups
+Virtual Groups
-* Virtual Groups:: Combining articles from many groups.
+* Selection Groups:: Articles selected from many places.
+* Combined Groups:: Combining multiple groups.
Email Based Diary
@@ -827,6 +829,7 @@ Various
* Spam Package:: A package for filtering and processing spam.
* The Gnus Registry:: A package for tracking messages by Message-ID.
* The Gnus Cloud:: A package for synchronizing Gnus marks.
+* D-Bus Integration:: Closing Gnus servers on system sleep.
* Other modes:: Interaction with other modes.
* Various Various:: Things that are really various.
@@ -946,6 +949,140 @@ Emacs for Heathens
@end detailmenu
@end menu
+@node Don't Panic
+@chapter Don't Panic
+@cindex don't panic
+@cindex introduction to Gnus
+
+Welcome, gentle user, to the Gnus newsreader and email client! Gnus
+is unlike most clients, in part because of its endless
+configurability, in part because of its historical origins. Gnus is
+now a fully-featured email client, but it began life as a Usenet-style
+newsreader, and its genes are still newsreader genes. Thus it behaves
+a little differently than most mail clients.
+
+The typical assumptions of a newsreader are:
+
+@enumerate
+@item
+The server offers a potentially enormous number of newsgroups on a
+variety of subjects. The user may only be interested in some of those
+groups, and more interested in some than others.
+@item
+Many groups see a high volume of articles, and the user won't want to
+read all of them. Mechanisms are needed for foregrounding interesting
+articles, and backgrounding uninteresting articles.
+@item
+Once a group has been scanned and dealt with by the user, it's
+unlikely to be of further interest until new articles come in.
+@end enumerate
+
+These assumptions lead to certain default Gnus behaviors:
+
+@enumerate
+@item
+Not all interesting groups are equally interesting, thus groups have
+varying degrees of ``subscribedness'', with different behavior
+depending on ``how subscribed'' a group is.
+@item
+There are many commands and tools for scoring and sorting articles,
+or otherwise sweeping them under the rug.
+@item
+Gnus will only show you groups with unread or ticked articles;
+groups with no new articles are hidden.
+@item
+When entering a group, only unread or ticked articles are shown,
+all other articles are hidden.
+@end enumerate
+
+If this seems draconian, think of it as Automatic Inbox Zero. This is
+the way Gnus works by default. It is possible to make it work more
+like an email client (always showing read groups and read articles),
+but that takes some effort on the part of the user.
+
+The brief introduction below should be enough to get you off the
+ground.
+
+@heading The Basics of Servers, Groups, and Articles
+@cindex servers
+@cindex groups
+@cindex articles
+
+The fundamental building blocks of Gnus are @dfn{servers},
+@dfn{groups}, and @dfn{articles}. Servers can be local or remote.
+Each server maintains a list of groups, and those groups contain
+articles. Because Gnus presents a unified interface to a wide variety
+of servers, the vocabulary doesn't always quite line up (see @ref{FAQ
+- Glossary}, for a more complete glossary). Thus a local maildir is
+referred to as a ``server'' (@pxref{Finding the News}) the same as a
+Usenet or IMAP server is; ``groups'' (@pxref{Group Buffer}) might mean
+an NNTP group, IMAP folder, or local mail directory; and an
+``article'' (@pxref{Summary Buffer}) might elsewhere be known as a
+message or an email. Gnus employs unified terms for all these things.
+
+Servers fall into two general categories: ``news-like'', meaning that
+the articles are part of a public archive and can't be manipulated by
+the user; and ``mail-like'', meaning that the articles are owned by
+the user, who can freely edit them, move them around, and delete
+them.
+
+For news-like servers, which typically offer hundreds or thousands of
+groups, it's important to be able to subscribe to a subset of those
+groups. For mail-like servers, the user is generally automatically
+subscribed to all groups (though IMAP, for example, also allows
+selective subscription). To change group subscription, enter the
+Server buffer (with @kbd{^}) and press @kbd{@key{RET}} on the server
+in question. From here, Gnus provides commands to change or toggle
+your group subscriptions (@pxref{Browse Foreign Server}).
+
+A Gnus installation is basically just a list of one or more servers,
+plus the user's subscribed groups from those servers, plus articles in
+those groups.
+
+Servers can be added and configured in two places: in the user's
+gnus.el startup file, using the @code{gnus-select-method} and
+@code{gnus-secondary-select-methods} options, or within Gnus itself
+using interactive commands in the Server buffer. @xref{Finding
+the News}, for details.
+
+
+@heading Fetching Mail
+
+New mail has to come from somewhere. Some servers, such as NNTP or
+IMAP, are themselves responsible for fetching newly-arrived articles.
+Others, such as maildir or mbox servers, only store articles and don't
+fetch them from anywhere.
+
+In the latter case, Gnus provides for @code{mail sources}: places
+where new mail is fetched from. A mail source might be a local spool,
+or a remote POP server, or some other source of incoming articles.
+Mail sources are usually configured globally, but can be specified
+per-group (@pxref{Mail Sources} for more information).
+
+@xref{Scanning New Messages}, for details on fetching new mail.
+
+@heading Viewing Mail
+
+By default, Gnus's Group buffer only displays groups with unread
+articles. It is always possible to display all the groups temporarily
+with @kbd{L}, and to configure Gnus to always display some groups
+(@pxref{Listing Groups}).
+
+@xref{Selecting a Group}, for how to enter a group, and @pxref{Summary
+Buffer} for what to do once you're there.
+
+@heading Sending Mail
+
+New message composition can be initiated from the Group buffer
+(@pxref{Misc Group Stuff}). If you're in a Summary buffer, you can
+compose replies and forward emails in addition to starting new
+messages, see @ref{Summary Mail Commands}, for details.
+
+For information about what happens once you've started composing a
+message, see @ref{Composing Messages}. For information on setting up
+@acronym{SMTP} servers in particular, see @ref{Mail Variables, ,Mail
+Variables,message,Message manual}.
+
@node Starting Up
@chapter Starting Gnus
@cindex starting up
@@ -975,7 +1112,7 @@ terminology section (@pxref{Terminology}).
@menu
* Finding the News:: Choosing a method for getting news.
* The Server is Down:: How can I read my mail then?
-* Slave Gnusae:: You can have more than one Gnus active at a time.
+* Child Gnusae:: You can have more than one Gnus active at a time.
* New Groups:: What is Gnus supposed to do with new groups?
* Changing Servers:: You may want to move from one server to another.
* Startup Files:: Those pesky startup files---@file{.newsrc}.
@@ -1089,9 +1226,9 @@ your primary server---instead, it will just activate all groups on level
levels.) Also @pxref{Group Levels}.
-@node Slave Gnusae
-@section Slave Gnusae
-@cindex slave
+@node Child Gnusae
+@section Child Gnusae
+@cindex child
You might want to run more than one Emacs with more than one Gnus at the
same time. If you are using different @file{.newsrc} files (e.g., if you
@@ -1102,31 +1239,27 @@ The problem appears when you want to run two Gnusae that use the same
@file{.newsrc} file.
To work around that problem some, we here at the Think-Tank at the Gnus
-Towers have come up with a new concept: @dfn{Masters} and
-@dfn{slaves}. (We have applied for a patent on this concept, and have
-taken out a copyright on those words. If you wish to use those words in
-conjunction with each other, you have to send $1 per usage instance to
-me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
-Applications}) will be much more expensive, of course.)
-
-@findex gnus-slave
+Towers have come up with a new concept: @dfn{Parents} and
+@dfn{children}.
+
+@findex gnus-child
Anyway, you start one Gnus up the normal way with @kbd{M-x gnus} (or
-however you do it). Each subsequent slave Gnusae should be started with
-@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
-files, but instead save @dfn{slave files} that contain information only
-on what groups have been read in the slave session. When a master Gnus
-starts, it will read (and delete) these slave files, incorporating all
-information from them. (The slave files will be read in the sequence
+however you do it). Each subsequent child Gnusae should be started with
+@kbd{M-x gnus-child}. These children won't save normal @file{.newsrc}
+files, but instead save @dfn{child files} that contain information only
+on what groups have been read in the child session. When a parent Gnus
+starts, it will read (and delete) these child files, incorporating all
+information from them. (The child files will be read in the sequence
they were created, so the latest changes will have precedence.)
-Information from the slave files has, of course, precedence over the
-information in the normal (i.e., master) @file{.newsrc} file.
+Information from the child files has, of course, precedence over the
+information in the normal (i.e., parent) @file{.newsrc} file.
-If the @file{.newsrc*} files have not been saved in the master when the
-slave starts, you may be prompted as to whether to read an auto-save
-file. If you answer ``yes'', the unsaved changes to the master will be
-incorporated into the slave. If you answer ``no'', the slave may see some
-messages as unread that have been read in the master.
+If the @file{.newsrc*} files have not been saved in the parent when the
+child starts, you may be prompted as to whether to read an auto-save
+file. If you answer ``yes'', the unsaved changes to the parent will be
+incorporated into the child. If you answer ``no'', the child may see some
+messages as unread that have been read in the parent.
@@ -1562,12 +1695,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.
@@ -4840,6 +4967,15 @@ The address (from the @code{From} header). This works the same way as
the @code{a} spec.
@item L
Number of lines in the article.
+@item Z
+Retrieval Score Value (RSV) of the article; nil if not in an nnselect
+group.
+@item G
+Originating group name of the article; nil if not in an nnselect
+group.
+@item g
+Short form of the originating group name of the article; nil if not in
+an nnselect group.
@item c
Number of characters in the article. This specifier is not supported
in some methods (like nnfolder).
@@ -9069,6 +9205,9 @@ when filling.
@findex gnus-article-fill-long-lines
Fill long lines (@code{gnus-article-fill-long-lines}).
+You can give the command a numerical prefix to specify the width to use
+when filling.
+
@item W C
@kindex W C @r{(Summary)}
@findex gnus-article-capitalize-sentences
@@ -10277,12 +10416,20 @@ article (@code{gnus-summary-refer-references}).
@findex gnus-summary-refer-thread
@kindex A T @r{(Summary)}
Display the full thread where the current article appears
-(@code{gnus-summary-refer-thread}). This command has to fetch all the
-headers in the current group to work, so it usually takes a while. If
-you do it often, you may consider setting @code{gnus-fetch-old-headers}
-to @code{invisible} (@pxref{Filling In Threads}). This won't have any
-visible effects normally, but it'll make this command work a whole lot
-faster. Of course, it'll make group entry somewhat slow.
+(@code{gnus-summary-refer-thread}). By default this command looks for
+articles only in the current group. Some backends (currently only
+@code{nnimap}) know how to find articles in the thread directly. In
+other cases each header in the current group must be fetched and
+examined, so it usually takes a while. If you do it often, you may
+consider setting @code{gnus-fetch-old-headers} to @code{invisible}
+(@pxref{Filling In Threads}). This won't have any visible effects
+normally, but it'll make this command work a whole lot faster. Of
+course, it'll make group entry somewhat slow.
+
+@vindex gnus-refer-thread-use-search
+If @code{gnus-refer-thread-use-search} is non-nil then those backends
+that know how to find threads directly will search not just in the
+current group but all groups on the same server.
@vindex gnus-refer-thread-limit
The @code{gnus-refer-thread-limit} variable says how many old (i.e.,
@@ -10291,6 +10438,16 @@ fetch when doing this command. The default is 200. If @code{t}, all
the available headers will be fetched. This variable can be overridden
by giving the @kbd{A T} command a numerical prefix.
+@vindex gnus-refer-thread-limit-to-thread
+In most cases @code{gnus-refer-thread} adds any articles it finds to
+the current summary buffer. (When @code{gnus-refer-thread-use-search}
+is true and the initial referral starts from a summary buffer for a
+non-virtual group this may not be possible. In this case a new
+summary buffer is created holding a virtual group with the result of
+the thread search.) If @code{gnus-refer-thread-limit-to-thread} is
+non-nil then the summary buffer will be limited to articles in the
+thread.
+
@item M-^ (Summary)
@findex gnus-summary-refer-article
@kindex M-^ @r{(Summary)}
@@ -10900,14 +11057,14 @@ Go to the Gnus info node (@code{gnus-info-find-node}).
@table @kbd
-@item M-s
-@kindex M-s @r{(Summary)}
+@item M-s M-s
+@kindex M-s M-s @r{(Summary)}
@findex gnus-summary-search-article-forward
Search through all subsequent (raw) articles for a regexp
(@code{gnus-summary-search-article-forward}).
-@item M-r
-@kindex M-r @r{(Summary)}
+@item M-s M-r
+@kindex M-s M-r @r{(Summary)}
@findex gnus-summary-search-article-backward
Search through all previous (raw) articles for a regexp
(@code{gnus-summary-search-article-backward}).
@@ -13132,7 +13289,7 @@ The different methods all have their peculiarities, of course.
* Getting Mail:: Reading your personal mail with Gnus.
* Browsing the Web:: Getting messages from a plethora of Web sources.
* Other Sources:: Reading directories, files.
-* Combined Groups:: Combining groups into one group.
+* Virtual Groups:: Combining articles and groups together.
* Email Based Diary:: Using mails to manage diary events in Gnus.
* Gnus Unplugged:: Reading news and mail offline.
@end menu
@@ -17704,19 +17861,131 @@ methods, but want to only use secondary ones:
@end lisp
-@node Combined Groups
-@section Combined Groups
+@node Virtual Groups
+@section Virtual Groups
-Gnus allows combining a mixture of all the other group types into bigger
-groups.
+Gnus allows combining articles from many sources, and combinations of
+whole groups together into virtual groups.
@menu
-* Virtual Groups:: Combining articles from many groups.
+* Selection Groups:: Combining articles from many groups.
+* Combined Groups:: Combining multiple groups.
@end menu
-@node Virtual Groups
-@subsection Virtual Groups
+@node Selection Groups
+@subsection Select Groups
+@cindex nnselect
+@cindex select groups
+@cindex selecting articles
+
+
+Gnus provides the @dfn{nnselect} method for creating virtual groups
+composed of collections of messages, even when these messages come
+from groups that span multiple servers and backends. For the most
+part these virtual groups behave like any other group: messages may be
+threaded, marked, moved, deleted, copied, etc.; groups may be
+ephemeral or persistent; groups may be created via
+@code{gnus-group-make-group} or browsed as foreign via
+@code{gnus-group-browse-foreign-server}.
+
+The key to using an nnselect group is specifying the messages to
+include. Each nnselect group has a group parameter
+@code{nnselect-specs} which is an alist with two elements: a function
+@code{nnselect-function}; and arguments @code{nnselect-args} to be
+passed to the function, if any.
+
+The function @code{nnselect-function} must return a vector. Each
+element of this vector is in turn a 3-element vector corresponding to
+one message. The 3 elements are: the fully-qualified group name; the
+message number; and a "score" that can be used for additional sorting.
+The values for the score are arbitrary, and are not used directly by
+the nnselect method---they may, for example, all be set to 100.
+
+Here is an example:
+
+@lisp
+(nnselect-specs
+ (nnselect-function . identity)
+ (nnselect-args
+ . [["nnimap+work:mail" 595 100]
+ ["nnimap+home:sent" 223 100]
+ ["nntp+news.gmane.org:gmane.emacs.gnus.general" 23666 100]]))
+@end lisp
+
+The function is the identity and the argument is just the list of
+messages to include in the virtual group.
+
+Or we may wish to create a group from the results of a search query:
+
+@lisp
+(nnselect-specs
+ (nnselect-function . nnir-run-query)
+ (nnselect-args
+ (nnir-query-spec
+ (query . "FLAGGED")
+ (criteria . ""))
+ (nnir-group-spec
+ ("nnimap:home")
+ ("nnimap:work"))))
+@end lisp
+
+This creates a group including all flagged messages from all groups on
+two IMAP servers, "home" and "work".
+
+And one last example. Here is a function that runs a search query to
+find all message that have been received recently from certain groups:
+
+@lisp
+(defun my-recent-email (args)
+ (let ((query-spec
+ (list
+ (cons 'query
+ (format-time-string "SENTSINCE %d-%b-%Y"
+ (time-subtract (current-time)
+ (days-to-time (car args)))))
+ (cons 'criteria "")))
+ (group-spec (cadr args)))
+ (nnir-run-query (cons 'nnir-specs
+ (list (cons 'nnir-query-spec query-spec)
+ (cons 'nnir-group-spec group-spec))))))
+@end lisp
+
+Then the following @code{nnselect-specs}:
+
+@lisp
+(nnselect-specs
+ (nnselect-function . my-recent-email)
+ (nnselect-args . (7 (("nnimap:home") ("nnimap:work")))))
+@end lisp
+
+will provide a group composed of all messages on the home and work
+servers received in the last 7 days.
+
+Refreshing the selection of an nnselect group by running the
+@code{nnselect-function} may take a long time to complete.
+Consequently nnselect groups are not refreshed by default when
+@code{gnus-group-get-new-news} is invoked. In those cases where
+running the function is not too time-consuming, a non-@code{nil} group
+parameter of @code{nnselect-rescan} will allow automatic refreshing.
+A refresh can always be invoked manually through
+@code{gnus-group-get-new-news-this-group}.
+
+The nnir interface (@pxref{nnir}) includes engines for searching a
+variety of backends. While the details of each search engine vary,
+the result of an nnir search is always a vector of the sort used by
+the nnselect method, and the results of nnir queries are usually
+viewed using an nnselect group. Indeed the standard search function
+@code{gnus-group-read-ephemeral-search-group} just creates an
+ephemeral nnselect group with the appropriate nnir query as the
+@code{nnselect-specs}. nnir originally included both the search
+engines and the glue to connect search results to gnus. Over time
+this glue evolved into the nnselect method. The two had a mostly
+amicable parting so that nnselect could pursue its dream of becoming a
+fully functioning backend, but occasional conflicts may still linger.
+
+@node Combined Groups
+@subsection Combined Groups
@cindex nnvirtual
@cindex virtual groups
@cindex merging groups
@@ -20077,6 +20346,24 @@ this will match articles that were posted when it was April 1st where
the article was posted from. Time zones are such wholesome fun for the
whole family, eh?)
+Finally, two actually useful match types for dates: @code{<} and
+@code{>}. These will allow scoring on the relative age (in days) of
+the articles. Here's an example score file using the method:
+
+@example
+(("date"
+ (7 10 nil <)
+ (7 -10 nil >)
+ (14 -10 nil >)))
+@end example
+
+This results in articles less than a week old getting a 10 point
+increase, articles older than a week getting a 10 point decrease, and
+articles older than two weeks getting a cumulative 20 point decrease.
+
+The day can also be a floating point number: To score articles less
+than an hour old, you can say @samp{(0.04 10 nil <)}.
+
@item Head, Body, All
These three match keys use the same match types as the @code{From} (etc.)@:
header uses.
@@ -21108,14 +21395,25 @@ four days, Gnus will decay the scores four times, for instance.
@chapter Searching
@cindex searching
-FIXME: Add a brief overview of Gnus search capabilities. A brief
-comparison of nnir, nnmairix, contrib/gnus-namazu would be nice
-as well.
-
-This chapter describes tools for searching groups and servers for
-articles matching a query and then retrieving those articles. Gnus
-provides a simpler mechanism for searching through articles in a summary buffer
-to find those matching a pattern. @xref{Searching for Articles}.
+FIXME: A brief comparison of nnir, nnmairix, contrib/gnus-namazu would
+be nice.
+
+Gnus has various ways of finding articles that match certain criteria
+(from a particular author, on a certain subject, etc.). The simplest
+method is to enter a group and then either "limit" the summary buffer
+to the desired articles using the limiting commands (@xref{Limiting}),
+or searching through messages in the summary buffer (@xref{Searching
+for Articles}).
+
+Limiting commands and summary buffer searching work on subsets of the
+articles already fetched from the servers, and these commands won't
+query the server for additional articles. While simple, these methods
+are therefore inadequate if the desired articles span multiple groups,
+or if the group is so large that fetching all articles is impractical.
+Many backends (such as imap, notmuch, namazu, etc.) provide their own
+facilities to search for articles directly on the server and Gnus can
+take advantage of these methods. This chapter describes tools for
+searching groups and servers for articles matching a query.
@menu
* nnir:: Searching with various engines.
@@ -21145,7 +21443,7 @@ through mail and news repositories. Different backends (like
interface.
The @code{nnimap} search engine should work with no configuration.
-Other engines require a local index that needs to be created and
+Other engines may require a local index that needs to be created and
maintained outside of Gnus.
@@ -21153,23 +21451,29 @@ maintained outside of Gnus.
@subsection Basic Usage
In the group buffer typing @kbd{G G} will search the group on the
-current line by calling @code{gnus-group-make-nnir-group}. This prompts
-for a query string, creates an ephemeral @code{nnir} group containing
-the articles that match this query, and takes you to a summary buffer
-showing these articles. Articles may then be read, moved and deleted
-using the usual commands.
-
-The @code{nnir} group made in this way is an @code{ephemeral} group,
-and some changes are not permanent: aside from reading, moving, and
-deleting, you can't act on the original article. But there is an
-alternative: you can @emph{warp} (i.e., jump) to the original group
-for the article on the current line with @kbd{A W}, aka
-@code{gnus-warp-to-article}. Even better, the function
-@code{gnus-summary-refer-thread}, bound by default in summary buffers
-to @kbd{A T}, will first warp to the original group before it works
-its magic and includes all the articles in the thread. From here you
-can read, move and delete articles, but also copy them, alter article
-marks, whatever. Go nuts.
+current line by calling @code{gnus-group-read-ephemeral-search-group}.
+This prompts for a query string, creates an ephemeral @code{nnselect}
+group containing the articles that match this query, and takes you to
+a summary buffer showing these articles. Articles may then be read,
+moved and deleted using the usual commands.
+
+The @code{nnselect} group made in this way is @code{ephemeral}: it
+will disappear upon exit from the group. However changes made in the
+group are permanently reflected in the real groups from which the
+articles are drawn. If you want to create a @emph{persistent} group
+that sticks around after exit from the summary buffer, you can call
+@code{gnus-group-make-search-group} (bound to @kbd{G g}).
+
+So you just performed a search whose results are so fabulous you
+wished you had done a persistent search rather than an ephemeral one?
+No problem; you can create such a group by calling
+@code{gnus-summary-make-group-from-search} (bound to @kbd{C-c C-p})
+from the ephemeral summary buffer.
+
+It is occasionally convenient to view articles found through searching
+in their original group. You can @emph{warp} (i.e., jump) to the
+original group for the article on the current line with @kbd{A W}, aka
+@code{gnus-warp-to-article}.
You say you want to search more than just the group on the current line?
No problem: just process-mark the groups you want to search. You want
@@ -21177,16 +21481,17 @@ even more? Calling for an nnir search with the cursor on a topic heading
will search all the groups under that heading.
Still not enough? OK, in the server buffer
-@code{gnus-group-make-nnir-group} (now bound to @kbd{G}) will search all
-groups from the server on the current line. Too much? Want to ignore
-certain groups when searching, like spam groups? Just customize
-@code{nnir-ignored-newsgroups}.
+@code{gnus-group-read-ephemeral-search-group} (now bound to @kbd{G})
+will search all groups from the server on the current line. Too much?
+Want to ignore certain groups when searching, like spam groups? Just
+customize @code{nnir-ignored-newsgroups}.
One more thing: individual search engines may have special search
-features. You can access these special features by giving a prefix-arg
-to @code{gnus-group-make-nnir-group}. If you are searching multiple
-groups with different search engines you will be prompted for the
-special search features for each engine separately.
+features. You can access these special features by giving a
+prefix-arg to @code{gnus-group-read-ephemeral-search-group}. If you
+are searching multiple groups with different search engines you will
+be prompted for the special search features for each engine
+separately.
@node Setting up nnir
@@ -21241,8 +21546,7 @@ variable is set to use the @code{imap} engine for all servers using the
your servers with an @code{nnimap} backend you could change this to
@lisp
-'((nnimap . namazu)
- (nntp . gmane))
+'((nnimap . namazu))
@end lisp
@node The imap Engine
@@ -21445,7 +21749,7 @@ This engine is obsolete.
@item nnir-method-default-engines
Alist of pairs of server backends and search engines. The default
-associations are
+association is
@example
(nnimap . imap)
@end example
@@ -21454,32 +21758,6 @@ associations are
A regexp to match newsgroups in the active file that should be skipped
when searching all groups on a server.
-@item nnir-summary-line-format
-The format specification to be used for lines in an nnir summary buffer.
-All the items from @code{gnus-summary-line-format} are available, along with
-three items unique to nnir summary buffers:
-
-@example
-%Z Search retrieval score value (integer)
-%G Article original full group name (string)
-%g Article original short group name (string)
-@end example
-
-If @code{nil} (the default) this will use @code{gnus-summary-line-format}.
-
-@item nnir-retrieve-headers-override-function
-If non-@code{nil}, a function that retrieves article headers rather than using
-the gnus built-in function. This function takes an article list and
-group as arguments and populates the @code{nntp-server-buffer} with the
-retrieved headers. It should then return either 'nov or 'headers
-indicating the retrieved header format. Failure to retrieve headers
-should return @code{nil}.
-
-If this variable is @code{nil}, or if the provided function returns
-@code{nil} for a search result, @code{gnus-retrieve-headers} will be
-called instead."
-
-
@end table
@@ -22204,6 +22482,7 @@ to you, using @kbd{G b u} and updating the group will usually fix this.
* Spam Package:: A package for filtering and processing spam.
* The Gnus Registry:: A package for tracking messages by Message-ID.
* The Gnus Cloud:: A package for synchronizing Gnus marks.
+* D-Bus Integration:: Closing Gnus servers on system sleep.
* Other modes:: Interaction with other modes.
* Various Various:: Things that are really various.
@end menu
@@ -26257,6 +26536,26 @@ CloudSynchronizationDataPack(TM)s. It's easiest to set this from the
Server buffer (@pxref{Gnus Cloud Setup}).
@end defvar
+@node D-Bus Integration
+@section D-Bus Integration
+@cindex dbus
+@cindex D-Bus
+@cindex gnus-dbus
+@cindex system sleep
+@cindex closing servers automatically
+@cindex hung connections
+
+When using laptops or other systems that have a sleep or hibernate
+functionality, it's possible for long-running server connections to
+become ``hung'', requiring the user to manually close and re-open the
+connections after the system resumes. On systems compiled with D-Bus
+support (check the value of @code{(featurep 'dbusbind)}), Gnus can
+register a D-Bus signal to automatically close all server connections
+before the system goes to sleep. To enable this, set
+@code{gnus-dbus-close-on-sleep} to a non-nil value.
+
+For more information about D-Bus and Emacs, @pxref{Top,,, dbus, D-Bus integration in Emacs}.
+
@node Other modes
@section Interaction with other modes
@@ -27898,7 +28197,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.
@@ -28474,9 +28773,9 @@ entry.
The format spec @code{%C} for positioning point has changed to @code{%*}.
@item
-@code{gnus-slave-unplugged}
+@code{gnus-child-unplugged}
-A new command which starts Gnus offline in slave mode.
+A new command which starts Gnus offline in child mode.
@end itemize
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/message.texi b/doc/misc/message.texi
index bdd31b1fe49..b192822fac6 100644
--- a/doc/misc/message.texi
+++ b/doc/misc/message.texi
@@ -99,6 +99,7 @@ sending it.
* Resending:: Resending a mail message.
* Bouncing:: Bouncing a mail message.
* Mailing Lists:: Send mail to mailing lists.
+* System Mailer Setup:: Using Message as the system mailer.
@end menu
You can customize the Message Mode tool bar, see @kbd{M-x
@@ -529,6 +530,29 @@ It is considered good netiquette to honor MFT, as it is assumed the
fellow who posted a message knows where the followups need to go
better than you do.
+
+@node System Mailer Setup
+@section System Mailer Setup
+@cindex mailto:
+
+Emacs can be set up as the system mailer, so that Emacs is opened when
+you click on @samp{mailto:} links in other programs.
+
+How this is done varies from system to system, but commonly there's a
+way to set the default application for a @acronym{MIME} type, and the
+relevant type here is @samp{x-scheme-handler/mailto;}.
+
+The application to start should be @samp{"emacs -f message-mailto %u"}.
+This will start Emacs, and then run the @code{message-mailto}
+command. It will parse the given @acronym{URL}, and set up a Message
+buffer with the given parameters.
+
+For instance, @samp{mailto:larsi@@gnus.org?subject=This+is+a+test}
+will open a Message buffer with the @samp{To:} header filled in with
+@samp{"larsi@@gnus.org"} and the @samp{Subject:} header with
+@samp{"This is a test"}.
+
+
@node Commands
@chapter Commands
@@ -883,6 +907,18 @@ is a list, valid members are @code{type}, @code{description} and
@code{nil}, don't ask for options. If it is @code{t}, ask the user
whether or not to specify options.
+@vindex message-screenshot-command
+@findex message-insert-screenshot
+@cindex screenshots
+@kindex C-c C-p
+If your system supports it, you can also insert screenshots directly
+into the Message buffer. The @kbd{C-c C-p}
+(@code{message-insert-screenshot}) command inserts the image into the
+buffer as an @acronym{MML} part, and puts an image text property on
+top. The @code{message-screenshot-command} variable says what
+external command to use to take the screenshot. It defaults to
+@code{"import png:-"}, which is an ImageMagick command.
+
You can also create arbitrarily complex multiparts using the @acronym{MML}
language (@pxref{Composing, , Composing, emacs-mime, The Emacs MIME
Manual}).
@@ -1006,6 +1042,7 @@ and/or encrypted messages as explained in the following.
* Signing and encryption:: Signing and encrypting commands.
* Using S/MIME:: Using S/MIME
* Using OpenPGP:: Using OpenPGP
+* OpenPGP Header:: Adding OpenPGP headers to messages.
* Passphrase caching:: How to cache passphrases
* PGP Compatibility:: Compatibility with older implementations
* Encrypt-to-self:: Reading your own encrypted messages
@@ -1215,6 +1252,29 @@ according to two different standards, namely @acronym{PGP} or
@code{mml-default-sign-method} determine which variant to prefer,
@acronym{PGP/MIME} by default.
+@node OpenPGP Header
+@subsection OpenPGP Header
+
+The @samp{OpenPGP} header can be used to provide information about the
+sender's OpenPGP key. This is a formalization and modernization of
+the non-standard @samp{X-PGP-Key} (etc.) headers that have been in use
+for a long time. For more details, see
+@uref{https://tools.ietf.org/html/draft-josefsson-openpgp-mailnews-header}.
+
+@vindex message-openpgp-header
+To use this in Message, say:
+
+@lisp
+(add-hook 'message-header-setup-hook 'message-add-openpgp-header)
+@end lisp
+
+@noindent
+then customize the @code{message-openpgp-header} variable according to
+your PGP setup. The variable is a list of the key ID, the key URL or
+ASCII armored key, and the protection preference, one of
+@samp{"unprotected"}, @samp{"sign"}, @samp{"encrypt"} or
+@samp{"signencrypt"}.
+
@node Passphrase caching
@subsection Passphrase caching
@@ -2236,8 +2296,11 @@ String to mark the end of some inserted text.
String to be inserted at the end of the message buffer. If @code{t}
(which is the default), the @code{message-signature-file} file will be
inserted instead. If a function, the result from the function will be
-used instead. If a form, the result from the form will be used instead.
-If this variable is @code{nil}, no signature will be inserted at all.
+used instead. If a form, the result from the form will be used
+instead. If this variable is @code{nil}, no signature will be
+inserted at all, but you can still insert your
+@code{message-signature-file} by hand when desired, using the
+@kbd{C-c C-w} (@code{message-insert-signature}) command.
@item message-signature-file
@vindex message-signature-file
diff --git a/doc/misc/org.texi b/doc/misc/org.texi
index 6f6fcd640d0..495d562f50b 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..f4367b35377 100644
--- a/doc/misc/smtpmail.texi
+++ b/doc/misc/smtpmail.texi
@@ -267,10 +267,12 @@ file, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
The process by which the SMTP library authenticates you to the server
is known as ``Simple Authentication and Security Layer'' (SASL).
There are various SASL mechanisms, and this library supports three of
-them: CRAM-MD5, PLAIN, and LOGIN@. It tries each of them, in that order,
-until one succeeds. The first uses a form of encryption to obscure
-your password, while the other two do not.
-
+them: CRAM-MD5, PLAIN, and LOGIN, where the first uses a form of
+encryption to obscure your password, while the other two do not. It
+tries each of them, in that order, until one succeeds. You can
+override this by assigning a specific authentication mechanism to a
+server by including a key @code{smtp-auth} with the value of your
+preferred mechanism in the appropriate @file{~/.authinfo} entry.
@node Encryption
@chapter Encryption
@@ -295,26 +297,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..0d2a1fdbc8f 100644
--- a/doc/misc/texinfo.tex
+++ b/doc/misc/texinfo.tex
@@ -3,9 +3,9 @@
% Load plain if necessary, i.e., if running under initex.
\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
%
-\def\texinfoversion{2019-09-24.13}
+\def\texinfoversion{2020-06-25.17}
%
-% Copyright 1985--1986, 1988, 1990--2020 Free Software Foundation, Inc.
+% Copyright 1985, 1986, 1988, 1990-2020 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
@@ -33,7 +33,7 @@
% The texinfo.tex in any given distribution could well be out
% of date, so if that's what you're using, please check.
%
-% Send bug reports to bug-texinfo@gnu.org. Please include including a
+% Send bug reports to bug-texinfo@gnu.org. Please include a
% complete document in each bug report with which we can reproduce the
% problem. Patches are, of course, greatly appreciated.
%
@@ -349,36 +349,21 @@
\ifodd\pageno \advance\hoffset by \bindingoffset
\else \advance\hoffset by -\bindingoffset\fi
%
+ \checkchapterpage
+ %
% Retrieve the information for the headings from the marks in the page,
% and call Plain TeX's \makeheadline and \makefootline, which use the
% values in \headline and \footline.
%
- % This is used to check if we are on the first page of a chapter.
- \ifcase1\the\savedtopmark\fi
- \let\prevchaptername\thischaptername
- \ifcase0\firstmark\fi
- \let\curchaptername\thischaptername
- %
- \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi
- %
- \ifx\curchaptername\prevchaptername
- \let\thischapterheading\thischapter
- \else
- % \thischapterheading is the same as \thischapter except it is blank
- % for the first page of a chapter. This is to prevent the chapter name
- % being shown twice.
- \def\thischapterheading{}%
- \fi
- %
% Common context changes for both heading and footing.
% Do this outside of the \shipout so @code etc. will be expanded in
% the headline as they should be, not taken literally (outputting ''code).
- \def\commmonheadfootline{\let\hsize=\txipagewidth \texinfochars}
- %
- \global\setbox\headlinebox = \vbox{\commmonheadfootline \makeheadline}%
+ \def\commonheadfootline{\let\hsize=\txipagewidth \texinfochars}
%
+ \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi
+ \global\setbox\headlinebox = \vbox{\commonheadfootline \makeheadline}%
\ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi
- \global\setbox\footlinebox = \vbox{\commmonheadfootline \makefootline}%
+ \global\setbox\footlinebox = \vbox{\commonheadfootline \makefootline}%
%
{%
% Set context for writing to auxiliary files like index files.
@@ -423,6 +408,22 @@
\ifr@ggedbottom \kern-\dimen@ \vfil \fi}
}
+% Check if we are on the first page of a chapter. Used for printing headings.
+\newif\ifchapterpage
+\def\checkchapterpage{%
+ % Get the chapter that was current at the end of the last page
+ \ifcase1\the\savedtopmark\fi
+ \let\prevchaptername\thischaptername
+ %
+ \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi
+ \let\curchaptername\thischaptername
+ %
+ \ifx\curchaptername\prevchaptername
+ \chapterpagefalse
+ \else
+ \chapterpagetrue
+ \fi
+}
% Argument parsing
@@ -1010,7 +1011,7 @@ where each line of input produces a line of output.}
\let\setfilename=\comment
% @bye.
-\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend}
+\outer\def\bye{\chappager\pagelabels\tracingstats=1\ptexend}
\message{pdf,}
@@ -1137,6 +1138,45 @@ where each line of input produces a line of output.}
\fi
+% Output page labels information.
+% See PDF reference v.1.7 p.594, section 8.3.1.
+\ifpdf
+\def\pagelabels{%
+ \def\title{0 << /P (T-) /S /D >>}%
+ \edef\roman{\the\romancount << /S /r >>}%
+ \edef\arabic{\the\arabiccount << /S /D >>}%
+ %
+ % Page label ranges must be increasing. Remove any duplicates.
+ % (There is a slight chance of this being wrong if e.g. there is
+ % a @contents but no @titlepage, etc.)
+ %
+ \ifnum\romancount=0 \def\roman{}\fi
+ \ifnum\arabiccount=0 \def\title{}%
+ \else
+ \ifnum\romancount=\arabiccount \def\roman{}\fi
+ \fi
+ %
+ \ifnum\romancount<\arabiccount
+ \pdfcatalog{/PageLabels << /Nums [\title \roman \arabic ] >> }\relax
+ \else
+ \pdfcatalog{/PageLabels << /Nums [\title \arabic \roman ] >> }\relax
+ \fi
+}
+\else
+ \let\pagelabels\relax
+\fi
+
+\newcount\pagecount \pagecount=0
+\newcount\romancount \romancount=0
+\newcount\arabiccount \arabiccount=0
+\ifpdf
+ \let\ptxadvancepageno\advancepageno
+ \def\advancepageno{%
+ \ptxadvancepageno\global\advance\pagecount by 1
+ }
+\fi
+
+
% PDF uses PostScript string constants for the names of xref targets,
% for display in the outlines, and in other places. Thus, we have to
% double any backslashes. Otherwise, a name like "\node" will be
@@ -1427,7 +1467,13 @@ output) for that.)}
% subentries, which we calculated on our first read of the .toc above.
%
% We use the node names as the destinations.
+ %
+ % Currently we prefix the section name with the section number
+ % for chapter and appendix headings only in order to avoid too much
+ % horizontal space being required in the PDF viewer.
\def\numchapentry##1##2##3##4{%
+ \dopdfoutline{##2 ##1}{count-\expnumber{chap##2}}{##3}{##4}}%
+ \def\unnchapentry##1##2##3##4{%
\dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}%
\def\numsecentry##1##2##3##4{%
\dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}%
@@ -1669,9 +1715,13 @@ output) for that.)}
% Therefore, we read toc only once.
%
% We use node names as destinations.
+ %
+ % Currently we prefix the section name with the section number
+ % for chapter and appendix headings only in order to avoid too much
+ % horizontal space being required in the PDF viewer.
\def\partentry##1##2##3##4{}% ignore parts in the outlines
\def\numchapentry##1##2##3##4{%
- \dopdfoutline{##1}{1}{##3}{##4}}%
+ \dopdfoutline{##2 ##1}{1}{##3}{##4}}%
\def\numsecentry##1##2##3##4{%
\dopdfoutline{##1}{2}{##3}{##4}}%
\def\numsubsecentry##1##2##3##4{%
@@ -1683,7 +1733,8 @@ output) for that.)}
\let\appsecentry\numsecentry%
\let\appsubsecentry\numsubsecentry%
\let\appsubsubsecentry\numsubsubsecentry%
- \let\unnchapentry\numchapentry%
+ \def\unnchapentry##1##2##3##4{%
+ \dopdfoutline{##1}{1}{##3}{##4}}%
\let\unnsecentry\numsecentry%
\let\unnsubsecentry\numsubsecentry%
\let\unnsubsubsecentry\numsubsubsecentry%
@@ -2496,7 +2547,7 @@ end
\def\it{\fam=\itfam \setfontstyle{it}}
\def\sl{\fam=\slfam \setfontstyle{sl}}
\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf}
-\def\tt{\fam=\ttfam \setfontstyle{tt}}
+\def\tt{\fam=\ttfam \setfontstyle{tt}}\def\ttstylename{tt}
% Texinfo sort of supports the sans serif font style, which plain TeX does not.
% So we set up a \sf.
@@ -3101,15 +3152,15 @@ end
% Allow a ragged right output to aid breaking long URL's. There can
% be a break at the \allowbreak with no extra glue (if the existing stretch in
-% the line is sufficent), a break at the \penalty100 with extra glue added
+% the line is sufficient), a break at the \penalty100 with extra glue added
% at the end of the line, or no break at all here.
% Changing the value of the penalty and/or the amount of stretch affects how
-% preferrable one choice is over the other.
+% preferable one choice is over the other.
\def\urefallowbreak{%
\allowbreak
- \hskip 0pt plus 4 em\relax
- \penalty100
- \hskip 0pt plus -4 em\relax
+ \hskip 0pt plus 2 em\relax
+ \penalty300
+ \hskip 0pt plus -2 em\relax
}
\urefbreakstyle after
@@ -3509,7 +3560,7 @@ end
% @pounds{} is a sterling sign, which Knuth put in the CM italic font.
%
-\def\pounds{{\it\$}}
+\def\pounds{\ifmonospace{\ecfont\char"BF}\else{\it\$}\fi}
% @euro{} comes from a separate font, depending on the current style.
% We use the free feym* fonts from the eurosym package by Henrik
@@ -3658,11 +3709,19 @@ end
\fi
% Quotes.
-\chardef\quotedblleft="5C
-\chardef\quotedblright=`\"
\chardef\quoteleft=`\`
\chardef\quoteright=`\'
+% only change font for tt for correct kerning and to avoid using
+% \ecfont unless necessary.
+\def\quotedblleft{%
+ \ifmonospace{\ecfont\char"10}\else{\char"5C}\fi
+}
+
+\def\quotedblright{%
+ \ifmonospace{\ecfont\char"11}\else{\char`\"}\fi
+}
+
\message{page headings,}
@@ -3784,12 +3843,19 @@ end
\newtoks\evenheadline % headline on even pages
\newtoks\oddheadline % headline on odd pages
+\newtoks\evenchapheadline% headline on even pages with a new chapter
+\newtoks\oddchapheadline % headline on odd pages with a new chapter
\newtoks\evenfootline % footline on even pages
\newtoks\oddfootline % footline on odd pages
% Now make \makeheadline and \makefootline in Plain TeX use those variables
-\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline
- \else \the\evenheadline \fi}}
+\headline={{\textfonts\rm
+ \ifchapterpage
+ \ifodd\pageno\the\oddchapheadline\else\the\evenchapheadline\fi
+ \else
+ \ifodd\pageno\the\oddheadline\else\the\evenheadline\fi
+ \fi}}
+
\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline
\else \the\evenfootline \fi}\HEADINGShook}
\let\HEADINGShook=\relax
@@ -3805,12 +3871,14 @@ end
\def\evenheading{\parsearg\evenheadingxxx}
\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish}
\def\evenheadingyyy #1\|#2\|#3\|#4\finish{%
-\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+ \global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}
+ \global\evenchapheadline=\evenheadline}
\def\oddheading{\parsearg\oddheadingxxx}
\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish}
\def\oddheadingyyy #1\|#2\|#3\|#4\finish{%
-\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+ \global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}%
+ \global\oddchapheadline=\oddheadline}
\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}%
@@ -3877,37 +3945,34 @@ end
\parseargdef\headings{\csname HEADINGS#1\endcsname}
\def\headingsoff{% non-global headings elimination
- \evenheadline={\hfil}\evenfootline={\hfil}%
- \oddheadline={\hfil}\oddfootline={\hfil}%
+ \evenheadline={\hfil}\evenfootline={\hfil}\evenchapheadline={\hfil}%
+ \oddheadline={\hfil}\oddfootline={\hfil}\oddchapheadline={\hfil}%
}
\def\HEADINGSoff{{\globaldefs=1 \headingsoff}} % global setting
\HEADINGSoff % it's the default
% When we turn headings on, set the page number to 1.
+\def\pageone{
+ \global\pageno=1
+ \global\arabiccount = \pagecount
+}
+
% For double-sided printing, put current file name in lower left corner,
% chapter name on inside top of right hand pages, document
% title on inside top of left hand pages, and page numbers on outside top
% edge of all pages.
\def\HEADINGSdouble{%
-\global\pageno=1
-\global\evenfootline={\hfil}
-\global\oddfootline={\hfil}
-\global\evenheadline={\line{\folio\hfil\thistitle}}
-\global\oddheadline={\line{\thischapterheading\hfil\folio}}
-\global\let\contentsalignmacro = \chapoddpage
+\pageone
+\HEADINGSdoublex
}
\let\contentsalignmacro = \chappager
% For single-sided printing, chapter title goes across top left of page,
% page number on top right.
\def\HEADINGSsingle{%
-\global\pageno=1
-\global\evenfootline={\hfil}
-\global\oddfootline={\hfil}
-\global\evenheadline={\line{\thischapterheading\hfil\folio}}
-\global\oddheadline={\line{\thischapterheading\hfil\folio}}
-\global\let\contentsalignmacro = \chappager
+\pageone
+\HEADINGSsinglex
}
\def\HEADINGSon{\HEADINGSdouble}
@@ -3917,7 +3982,9 @@ end
\global\evenfootline={\hfil}
\global\oddfootline={\hfil}
\global\evenheadline={\line{\folio\hfil\thistitle}}
-\global\oddheadline={\line{\thischapterheading\hfil\folio}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\evenchapheadline={\line{\folio\hfil}}
+\global\oddchapheadline={\line{\hfil\folio}}
\global\let\contentsalignmacro = \chapoddpage
}
@@ -3925,8 +3992,22 @@ end
\def\HEADINGSsinglex{%
\global\evenfootline={\hfil}
\global\oddfootline={\hfil}
-\global\evenheadline={\line{\thischapterheading\hfil\folio}}
-\global\oddheadline={\line{\thischapterheading\hfil\folio}}
+\global\evenheadline={\line{\thischapter\hfil\folio}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\evenchapheadline={\line{\hfil\folio}}
+\global\oddchapheadline={\line{\hfil\folio}}
+\global\let\contentsalignmacro = \chappager
+}
+
+% for @setchapternewpage off
+\def\HEADINGSsinglechapoff{%
+\pageone
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\thischapter\hfil\folio}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\evenchapheadline=\evenheadline
+\global\oddchapheadline=\oddheadline
\global\let\contentsalignmacro = \chappager
}
@@ -4841,7 +4922,7 @@ end
% like the previous two, but they put @code around the argument.
\def\docodeindex#1{\edef\indexname{#1}\parsearg\docodeindexxxx}
-\def\docodeindexxxx #1{\doind{\indexname}{\code{#1}}}
+\def\docodeindexxxx #1{\docind{\indexname}{#1}}
% Used for the aux, toc and index files to prevent expansion of Texinfo
@@ -5117,64 +5198,66 @@ end
\let\lbracechar\{%
\let\rbracechar\}%
%
+ %
+ \let\do\indexnofontsdef
+ %
% Non-English letters.
- \def\AA{AA}%
- \def\AE{AE}%
- \def\DH{DZZ}%
- \def\L{L}%
- \def\OE{OE}%
- \def\O{O}%
- \def\TH{TH}%
- \def\aa{aa}%
- \def\ae{ae}%
- \def\dh{dzz}%
- \def\exclamdown{!}%
- \def\l{l}%
- \def\oe{oe}%
- \def\ordf{a}%
- \def\ordm{o}%
- \def\o{o}%
- \def\questiondown{?}%
- \def\ss{ss}%
- \def\th{th}%
- %
- \def\LaTeX{LaTeX}%
- \def\TeX{TeX}%
- %
- % Assorted special characters. \defglyph gives the control sequence a
- % definition that removes the {} that follows its use.
- \defglyph\atchar{@}%
- \defglyph\arrow{->}%
- \defglyph\bullet{bullet}%
- \defglyph\comma{,}%
- \defglyph\copyright{copyright}%
- \defglyph\dots{...}%
- \defglyph\enddots{...}%
- \defglyph\equiv{==}%
- \defglyph\error{error}%
- \defglyph\euro{euro}%
- \defglyph\expansion{==>}%
- \defglyph\geq{>=}%
- \defglyph\guillemetleft{<<}%
- \defglyph\guillemetright{>>}%
- \defglyph\guilsinglleft{<}%
- \defglyph\guilsinglright{>}%
- \defglyph\leq{<=}%
- \defglyph\lbracechar{\{}%
- \defglyph\minus{-}%
- \defglyph\point{.}%
- \defglyph\pounds{pounds}%
- \defglyph\print{-|}%
- \defglyph\quotedblbase{"}%
- \defglyph\quotedblleft{"}%
- \defglyph\quotedblright{"}%
- \defglyph\quoteleft{`}%
- \defglyph\quoteright{'}%
- \defglyph\quotesinglbase{,}%
- \defglyph\rbracechar{\}}%
- \defglyph\registeredsymbol{R}%
- \defglyph\result{=>}%
- \defglyph\textdegree{o}%
+ \do\AA{AA}%
+ \do\AE{AE}%
+ \do\DH{DZZ}%
+ \do\L{L}%
+ \do\OE{OE}%
+ \do\O{O}%
+ \do\TH{TH}%
+ \do\aa{aa}%
+ \do\ae{ae}%
+ \do\dh{dzz}%
+ \do\exclamdown{!}%
+ \do\l{l}%
+ \do\oe{oe}%
+ \do\ordf{a}%
+ \do\ordm{o}%
+ \do\o{o}%
+ \do\questiondown{?}%
+ \do\ss{ss}%
+ \do\th{th}%
+ %
+ \do\LaTeX{LaTeX}%
+ \do\TeX{TeX}%
+ %
+ % Assorted special characters.
+ \do\atchar{@}%
+ \do\arrow{->}%
+ \do\bullet{bullet}%
+ \do\comma{,}%
+ \do\copyright{copyright}%
+ \do\dots{...}%
+ \do\enddots{...}%
+ \do\equiv{==}%
+ \do\error{error}%
+ \do\euro{euro}%
+ \do\expansion{==>}%
+ \do\geq{>=}%
+ \do\guillemetleft{<<}%
+ \do\guillemetright{>>}%
+ \do\guilsinglleft{<}%
+ \do\guilsinglright{>}%
+ \do\leq{<=}%
+ \do\lbracechar{\{}%
+ \do\minus{-}%
+ \do\point{.}%
+ \do\pounds{pounds}%
+ \do\print{-|}%
+ \do\quotedblbase{"}%
+ \do\quotedblleft{"}%
+ \do\quotedblright{"}%
+ \do\quoteleft{`}%
+ \do\quoteright{'}%
+ \do\quotesinglbase{,}%
+ \do\rbracechar{\}}%
+ \do\registeredsymbol{R}%
+ \do\result{=>}%
+ \do\textdegree{o}%
%
% We need to get rid of all macros, leaving only the arguments (if present).
% Of course this is not nearly correct, but it is the best we can do for now.
@@ -5189,7 +5272,10 @@ end
\macrolist
\let\value\indexnofontsvalue
}
-\def\defglyph#1#2{\def#1##1{#2}} % see above
+
+% Give the control sequence a definition that removes the {} that follows
+% its use, e.g. @AA{} -> AA
+\def\indexnofontsdef#1#2{\def#1##1{#2}}%
@@ -5208,6 +5294,20 @@ end
\fi
}
+% Same as \doind, but for code indices
+\def\docind#1#2{%
+ \iflinks
+ {%
+ %
+ \requireopenindexfile{#1}%
+ \edef\writeto{\csname#1indfile\endcsname}%
+ %
+ \def\indextext{#2}%
+ \safewhatsit\docindwrite
+ }%
+ \fi
+}
+
% Check if an index file has been opened, and if not, open it.
\def\requireopenindexfile#1{%
\ifnum\csname #1indfile\endcsname=0
@@ -5274,6 +5374,9 @@ end
% trim spaces.
\edef\trimmed{\segment}%
\edef\trimmed{\expandafter\eatspaces\expandafter{\trimmed}}%
+ \ifincodeindex
+ \edef\trimmed{\noexpand\code{\trimmed}}%
+ \fi
%
\xdef\bracedtext{\bracedtext{\trimmed}}%
%
@@ -5339,7 +5442,12 @@ end
% Write the entry in \indextext to the index file.
%
-\def\doindwrite{%
+
+\newif\ifincodeindex
+\def\doindwrite{\incodeindexfalse\doindwritex}
+\def\docindwrite{\incodeindextrue\doindwritex}
+
+\def\doindwritex{%
\maybemarginindex
%
\atdummies
@@ -5559,7 +5667,11 @@ might help (with 'rm \jobname.?? \jobname.??s')%
\else
\begindoublecolumns
\catcode`\\=0\relax
- \catcode`\@=12\relax
+ %
+ % Make @ an escape character to give macros a chance to work. This
+ % should work because we (hopefully) don't otherwise use @ in index files.
+ %\catcode`\@=12\relax
+ \catcode`\@=0\relax
\input \jobname.\indexname s
\enddoublecolumns
\fi
@@ -6401,18 +6513,16 @@ might help (with 'rm \jobname.?? \jobname.??s')%
\def\CHAPPAGoff{%
\global\let\contentsalignmacro = \chappager
\global\let\pchapsepmacro=\chapbreak
-\global\let\pagealignmacro=\chappager}
+\global\def\HEADINGSon{\HEADINGSsinglechapoff}}
\def\CHAPPAGon{%
\global\let\contentsalignmacro = \chappager
\global\let\pchapsepmacro=\chappager
-\global\let\pagealignmacro=\chappager
\global\def\HEADINGSon{\HEADINGSsingle}}
\def\CHAPPAGodd{%
\global\let\contentsalignmacro = \chapoddpage
\global\let\pchapsepmacro=\chapoddpage
-\global\let\pagealignmacro=\chapoddpage
\global\def\HEADINGSon{\HEADINGSdouble}}
\CHAPPAGon
@@ -6777,9 +6887,7 @@ might help (with 'rm \jobname.?? \jobname.??s')%
%
\def\startcontents#1{%
% If @setchapternewpage on, and @headings double, the contents should
- % start on an odd page, unlike chapters. Thus, we maintain
- % \contentsalignmacro in parallel with \pagealignmacro.
- % From: Torbjorn Granlund <tege@matematik.su.se>
+ % start on an odd page, unlike chapters.
\contentsalignmacro
\immediate\closeout\tocfile
%
@@ -6794,6 +6902,9 @@ might help (with 'rm \jobname.?? \jobname.??s')%
%
% Roman numerals for page numbers.
\ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi
+ \def\thistitle{}% no title in double-sided headings
+ % Record where the Roman numerals started.
+ \ifnum\romancount=0 \global\romancount=\pagecount \fi
}
% redefined for the two-volume lispref. We always output on
@@ -6816,8 +6927,7 @@ might help (with 'rm \jobname.?? \jobname.??s')%
\fi
\closein 1
\endgroup
- \lastnegativepageno = \pageno
- \global\pageno = \savepageno
+ \contentsendroman
}
% And just the chapters.
@@ -6852,10 +6962,20 @@ might help (with 'rm \jobname.?? \jobname.??s')%
\vfill \eject
\contentsalignmacro % in case @setchapternewpage odd is in effect
\endgroup
+ \contentsendroman
+}
+\let\shortcontents = \summarycontents
+
+% Get ready to use Arabic numerals again
+\def\contentsendroman{%
\lastnegativepageno = \pageno
\global\pageno = \savepageno
+ %
+ % If \romancount > \arabiccount, the contents are at the end of the
+ % document. Otherwise, advance where the Arabic numerals start for
+ % the page numbers.
+ \ifnum\romancount>\arabiccount\else\global\arabiccount=\pagecount\fi
}
-\let\shortcontents = \summarycontents
% Typeset the label for a chapter or appendix for the short contents.
% The arg is, e.g., `A' for an appendix, or `3' for a chapter.
@@ -7444,13 +7564,9 @@ might help (with 'rm \jobname.?? \jobname.??s')%
\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount
%
% We typeset each line of the verbatim in an \hbox, so we can handle
-% tabs. The \global is in case the verbatim line starts with an accent,
-% or some other command that starts with a begin-group. Otherwise, the
-% entire \verbbox would disappear at the corresponding end-group, before
-% it is typeset. Meanwhile, we can't have nested verbatim commands
-% (can we?), so the \global won't be overwriting itself.
+% tabs.
\newbox\verbbox
-\def\starttabbox{\global\setbox\verbbox=\hbox\bgroup}
+\def\starttabbox{\setbox\verbbox=\hbox\bgroup}
%
\begingroup
\catcode`\^^I=\active
@@ -7461,7 +7577,8 @@ might help (with 'rm \jobname.?? \jobname.??s')%
\divide\dimen\verbbox by\tabw
\multiply\dimen\verbbox by\tabw % compute previous multiple of \tabw
\advance\dimen\verbbox by\tabw % advance to next multiple of \tabw
- \wd\verbbox=\dimen\verbbox \box\verbbox \starttabbox
+ \wd\verbbox=\dimen\verbbox
+ \leavevmode\box\verbbox \starttabbox
}%
}
\endgroup
@@ -7471,9 +7588,7 @@ might help (with 'rm \jobname.?? \jobname.??s')%
\let\nonarrowing = t%
\nonfillstart
\tt % easiest (and conventionally used) font for verbatim
- % The \leavevmode here is for blank lines. Otherwise, we would
- % never \starttabbox and the \egroup would end verbatim mode.
- \def\par{\leavevmode\egroup\box\verbbox\endgraf}%
+ \def\par{\egroup\leavevmode\box\verbbox\endgraf\starttabbox}%
\tabexpand
\setupmarkupstyle{verbatim}%
% Respect line breaks,
@@ -7481,7 +7596,6 @@ might help (with 'rm \jobname.?? \jobname.??s')%
% make each space count.
% Must do in this order:
\obeylines \uncatcodespecials \sepspaces
- \everypar{\starttabbox}%
}
% Do the @verb magic: verbatim text is quoted by unique
@@ -7516,9 +7630,12 @@ might help (with 'rm \jobname.?? \jobname.??s')%
% ignore everything up to the first ^^M, that's the newline at the end
% of the @verbatim input line itself. Otherwise we get an extra blank
% line in the output.
- \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}%
+ \xdef\doverbatim#1^^M#2@end verbatim{%
+ \starttabbox#2\egroup\noexpand\end\gobble verbatim}%
% We really want {...\end verbatim} in the body of the macro, but
% without the active space; thus we have to use \xdef and \gobble.
+ % The \egroup ends the \verbbox started at the end of the last line in
+ % the block.
\endgroup
%
\envdef\verbatim{%
@@ -7540,7 +7657,7 @@ might help (with 'rm \jobname.?? \jobname.??s')%
\wlog{texinfo.tex: doing @verbatiminclude of #1^^J}%
\edef\tmp{\noexpand\input #1 }
\expandafter
- }\tmp
+ }\expandafter\starttabbox\tmp\egroup
\afterenvbreak
}%
}
@@ -7690,7 +7807,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
@@ -8955,17 +9072,11 @@ might help (with 'rm \jobname.?? \jobname.??s')%
\else
% Reference within this manual.
%
- % _ (for example) has to be the character _ for the purposes of the
- % control sequence corresponding to the node, but it has to expand
- % into the usual \leavevmode...\vrule stuff for purposes of
- % printing. So we \turnoffactive for the \refx-snt, back on for the
- % printing, back off for the \refx-pg.
- {\turnoffactive
- % Only output a following space if the -snt ref is nonempty; for
- % @unnumbered and @anchor, it won't be.
- \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}%
- \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi
- }%
+ % Only output a following space if the -snt ref is nonempty; for
+ % @unnumbered and @anchor, it won't be.
+ \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}%
+ \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi
+ %
% output the `[mynode]' via the macro below so it can be overridden.
\xrefprintnodename\printedrefname
%
@@ -9055,7 +9166,7 @@ might help (with 'rm \jobname.?? \jobname.??s')%
\requireauxfile
{%
\indexnofonts
- \otherbackslash
+ \turnoffactive
\def\value##1{##1}%
\expandafter\global\expandafter\let\expandafter\thisrefX
\csname XR#1\endcsname
@@ -10712,6 +10823,8 @@ directory should work if nowhere else does.}
\DeclareUnicodeCharacter{0233}{\=y}%
\DeclareUnicodeCharacter{0237}{\dotless{j}}%
%
+ \DeclareUnicodeCharacter{02BC}{'}%
+ %
\DeclareUnicodeCharacter{02DB}{\ogonek{ }}%
%
% Greek letters upper case
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 97a26421f2f..bdf3b403d80 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
@@ -59,7 +59,7 @@ local and the remote host, whereas @value{tramp} uses a combination of
@command{ssh}/@command{scp}.
You can find the latest version of this document on the web at
-@uref{https://www.gnu.org/software/tramp/}.
+@uref{@value{trampurl}}.
@ifhtml
The latest release of @value{tramp} is available for
@@ -141,6 +141,7 @@ Configuring @value{tramp} for use
* Remote shell setup:: Remote shell setup hints.
* Android shell setup:: Android shell setup hints.
* Auto-save and Backup:: Auto-save and Backup.
+* Keeping files encrypted:: Protect remote files by encryption.
* Windows setup hints:: Issues with Cygwin ssh.
Using @value{tramp}
@@ -238,7 +239,7 @@ included in the file name portion, @value{tramp} sends the login name
followed by a newline.
@item
-The remote host may then prompt for a password or pass phrase (for
+The remote host may then prompt for a password or passphrase (for
@command{rsh} or for @command{telnet}). @value{tramp} displays the
password prompt in the minibuffer. @value{tramp} then sends whatever
is entered to the remote host, followed by a newline.
@@ -312,7 +313,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 +325,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.4.3.27.1''. This means @value{tramp} 2.4.3 as
-integrated in Emacs 27.1. A complete list of @value{tramp} versions
-packaged with Emacs can be retrieved by
+as suffix, like ``2.4.3.27.1''. This means @w{@value{tramp} 2.4.3} as
+integrated in @w{Emacs 27.1}. A complete list of @value{tramp}
+versions packaged with Emacs can be retrieved by
@vindex customize-package-emacs-version-alist
@lisp
@@ -557,13 +558,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}
@@ -664,6 +668,7 @@ might be used in your init file:
* Remote shell setup:: Remote shell setup hints.
* Android shell setup:: Android shell setup hints.
* Auto-save and Backup:: Auto-save and Backup.
+* Keeping files encrypted:: Protect remote files by encryption.
* Windows setup hints:: Issues with Cygwin ssh.
@end menu
@@ -1126,7 +1131,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}
@@ -1179,9 +1185,6 @@ for accessing the system storage, you shall prefer this.
@ref{GVFS-based methods} for example, methods @option{gdrive} and
@option{nextcloud}.
-@strong{Note}: The @option{rclone} method is experimental, don't use
-it in production systems!
-
@end table
@@ -1227,6 +1230,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 +1246,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 +1289,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 +1664,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
@@ -1708,6 +1730,7 @@ Convenience method to access vagrant boxes. It is often used in
multi-hop file names like
@file{@value{prefix}vagrant@value{postfixhop}box|sudo@value{postfixhop}box@value{postfix}/path/to/file},
where @samp{box} is the name of the vagrant box.
+
@end table
@@ -2030,6 +2053,13 @@ The temporary directory on the remote host. If not specified, the
default value is @t{"/data/local/tmp"} for the @option{adb} method,
@t{"/C$/Temp"} for the @option{smb} method, and @t{"/tmp"} otherwise.
+@item @t{"direct-async-process"}
+
+When this property is non-@code{nil}, an alternative, more performant
+implementation of @code{make-process} and
+@code{start-file-process} is applied. @ref{Improving performance of
+asynchronous remote processes} for a discussion of constraints.
+
@item @t{"posix"}
Connections using the @option{smb} method check, whether the remote
@@ -2075,7 +2105,7 @@ To improve performance and accuracy of remote file access,
@file{/usr/bin}, which are reasonable for most hosts. To accommodate
differences in hosts and paths, for example, @file{/bin:/usr/bin} on
Debian GNU/Linux or
-@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin} on
+@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/developerstudio12.6/bin} on
Solaris, @value{tramp} queries the remote host with @command{getconf
PATH} and updates the symbol @code{tramp-default-remote-path}.
@@ -2102,8 +2132,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
@@ -2435,10 +2465,9 @@ overwrite as follows:
@lisp
@group
-(add-to-list
- 'tramp-connection-properties
- `(,(regexp-quote "192.168.0.1")
- "remote-copy-args" (("-l") ("%r"))))
+(add-to-list 'tramp-connection-properties
+ `(,(regexp-quote "192.168.0.1")
+ "remote-copy-args" (("-l") ("%r"))))
@end group
@end lisp
@@ -2457,7 +2486,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}
@@ -2632,6 +2661,117 @@ auto-saved files to the same directory as the original file.
Alternatively, set the user option @code{tramp-auto-save-directory}
to direct all auto saves to that location.
+
+@node Keeping files encrypted
+@section Protect remote files by encryption
+@cindex Encrypt remote directories
+
+@strong{Note}: File encryption in @value{tramp} is experimental, don't
+use it in production systems!
+
+Sometimes, it is desirable to protect files located on remote
+directories, like cloud storages. In order to do this, you might
+instruct @value{tramp} to encrypt all files copied to a given remote
+directory, and to decrypt such files when accessing. This includes
+both file contents and file names.
+
+@value{tramp} does this transparently. Although both files and file
+names are encrypted on the remote side, they are accessible inside
+Emacs as they wouldn't be transformed as such.
+
+@cindex @command{encfs}
+@cindex @command{encfsctl}
+Internally, @value{tramp} uses the @command{encfs} package.
+Therefore, this feature is available only if this package is installed
+on the local host. @value{tramp} does not keep and @samp{encfs
+mountpoint} permanently. Instead, it encrypts / decrypts files and
+file names on the fly, using @command{encfsctl}.
+
+@deffn Command tramp-crypt-add-directory name
+This command marks the existing remote directory @var{name} for
+encryption. Files in that directory and all subdirectories will be
+encrypted before copying to, and decrypted after copying from that
+directory. File and directory names will be also encrypted.
+@end deffn
+
+@defopt tramp-crypt-encfs-option
+If a remote directory is marked for encryption, it is initialized via
+@command{encfs} the very first time a file in this directory is
+accessed. This user option controls, which default @command{encfs}
+configuration option will be selected, it can be @t{"--standard"}
+or @t{"--paranoia"}. See the @samp{encfs(1)} man page for details.
+
+However, @value{tramp} must adapt these configuration sets. The
+@code{chainedNameIV} configuration option must be disabled; otherwise
+@value{tramp} couldn't handle file name encryption transparently.
+@end defopt
+
+A password protected @option{encfs} configuration file is created the
+very first time you access an encrypted remote directory. It is kept
+in your @code{user-emacs-directory} with the url-encoded directory
+name as part of the basename, and @file{encfs6.xml} as suffix. If
+you, for example, mark the remote directory
+@file{@trampfn{nextcloud,user@@host,/path/to/dir}} for encryption, the
+configuration file is saved as
+@file{tramp-%2Fnextcloud%3Auser%40host%3A%2Fpath%2Fto%2Fdir%2F.encfs6.xml}
+in @code{user-emacs-directory}. Do not loose this file and the
+corresponding password; otherwise there is no way to decrypt your
+encrypted files.
+
+@defopt tramp-crypt-save-encfs-config-remote
+If this user option is non-nil (the default), the @option{encfs}
+configuration file @file{.encfs6.xml} is also kept in the encrypted
+remote directory. It depends on you, whether you regard the password
+protection of this file as sufficient. The advantage would be, that
+such a remote directory could be accessed by different Emacs sessions,
+different users, without presharing the configuration file between the
+users.
+@end defopt
+
+The command @command{encfsctl}, the workhorse for encryption /
+decryption, needs the configuration file password every call.
+Therefore, it is recommend to cache this password in Emacs. This can
+be done using @code{auth-sources}, @ref{Using an authentication file}.
+An entry needs the url-encoded directory name as machine, your local
+user name as user, and the password. The port is optional, if given
+it must be the string @t{"crypt"}. The example above would require
+the following entry in the authentication file (@t{"yourname"} is the
+result of @code{(user-login-name)}):
+
+@example
+machine %2Fnextcloud%3Auser%40host%3A%2Fpath%2Fto%2Fdir%2F \
+ login yourname port crypt password geheim
+@end example
+
+If you use a remote file name with a quoted localname part, this
+localname and the corresponding file will not be encrypted /
+decrypted. If you have an encrypted remote directory
+@file{@trampfn{nextcloud,user@@host,/path/to/dir}}, the command
+
+@example
+@kbd{C-x d @trampfn{nextcloud,user@@host,/path/to/dir}}
+@end example
+
+@noindent
+will show the directory listing with the plain file names, and the
+command
+
+@example
+@kbd{C-x d @trampfn{nextcloud,user@@host,/:/path/to/dir}}
+@end example
+
+@noindent
+will show the directory listing with the encrypted file names, and
+visiting a file will show its encrypted contents. However, it is
+highly discouraged to mix encrypted and not encrypted files in the
+same directory.
+
+@deffn Command tramp-crypt-add-directory name
+If a remote directory shall not include encrypted files anymore, it
+must be indicated by this command.
+@end deffn
+
+
@node Windows setup hints
@section Issues with Cygwin ssh
@cindex cygwin, issues
@@ -2665,10 +2805,10 @@ Wiki} it is explained how to use the helper program
@cindex @option{scpx} method with cygwin
When using the @option{scpx} access method, Emacs may call
-@command{scp} with MS Windows file naming, such as @code{c:/foo}. But
+@command{scp} with MS Windows file naming, such as @file{c:/foo}. But
the version of @command{scp} that is installed with Cygwin does not
know about MS Windows file naming, which causes it to incorrectly look
-for a host named @code{c}.
+for a host named @samp{c}.
A workaround: write a wrapper script for @option{scp} to convert
Windows file names to Cygwin file names.
@@ -2944,10 +3084,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
@@ -3187,8 +3327,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}.
@@ -3238,8 +3378,8 @@ host. Example:
@end group
@end example
-@command{tail} command outputs continuously to the local buffer,
-@file{*Async Shell Command*}
+@command{tail} command outputs continuously to the local buffer whose
+name is the value of the variable @code{shell-command-buffer-name-async}.
@kbd{M-x auto-revert-tail-mode @key{RET}} runs similarly showing
continuous output.
@@ -3257,10 +3397,10 @@ variables.
@vindex async-shell-command-width
@vindex COLUMNS@r{, environment variable}
If Emacs supports the variable @code{async-shell-command-width} (since
-Emacs 27), @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
+@w{Emacs 27}), @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
@code{tramp-remote-process-environment}.
@@ -3393,6 +3533,77 @@ To open @command{powershell} as a remote shell, use this:
@end lisp
+@anchor{Improving performance of asynchronous remote processes}
+@subsection Improving performance of asynchronous remote processes
+@cindex Asynchronous remote processes
+@findex make-process
+@findex start-file-process
+
+@value{tramp}'s implementation of @code{make-process} and
+@code{start-file-process} requires a serious overhead for
+initialization, every process invocation. This is needed for handling
+interactive dialogues when connecting the remote host (like providing
+a password), and initial environment setup.
+
+Sometimes, this is not needed. Instead of starting a remote shell and
+running the command afterwards, it is sufficient to run the command
+directly. @value{tramp} supports this by an alternative
+implementation of @code{make-process} and @code{start-file-process}.
+This is triggered by the connection property
+@t{"direct-async-process"}, @xref{Predefined connection information},
+which must be set to a non-@code{nil} value. Example:
+
+@lisp
+@group
+(add-to-list 'tramp-connection-properties
+ (list (regexp-quote "@trampfn{ssh,user@@host,}")
+ "direct-async-process" t))
+@end group
+@end lisp
+
+Using direct asynchronous processes in @value{tramp} is not possible,
+if the remote host is connected via multiple hops
+(@pxref{Multi-hops}). In this case, @value{tramp} falls back to its
+classical implementation.
+
+Furthermore, this approach has the following limitations:
+
+@itemize
+@item
+It works only for connection methods defined in @file{tramp-sh.el} and
+@file{tramp-adb.el}.
+
+@item
+It does not support interactive user authentication. With
+@option{ssh}-based methods, this can be avoided by using a password
+agent like @command{ssh-agent}, using public key authentication, or
+using @code{ControlMaster} options.
+
+@item
+It cannot be killed via @code{interrupt-process}.
+
+@item
+It does not report the remote terminal name via @code{process-tty-name}.
+
+@item
+It does not set process property @code{remote-pid}.
+
+@item
+It does not use @code{tramp-remote-path} and
+@code{tramp-remote-process-environment}.
+
+@item
+It does not set environment variable @env{INSIDE_EMACS}.
+@end itemize
+
+In order to gain even more performance, it is recommended to bind
+@code{tramp-verbose} to 0 when running @code{make-process} or
+@code{start-file-process}. Furthermore, you might set
+@code{tramp-use-ssh-controlmaster-options} to @code{nil} in order to
+bypass @value{tramp}'s handling of the @code{ControlMaster} options,
+and use your own settings in @file{~/.ssh/config}.
+
+
@node Cleanup remote connections
@section Cleanup remote connections
@cindex cleanup
@@ -3879,8 +4090,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, Emacs
-27, and Emacs 28.
+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
@@ -4142,8 +4353,8 @@ Host *
@end group
@end example
-Check @command{man ssh_config} whether these options are supported on
-your proxy host.
+Check the @samp{ssh_config(5)} man page whether these options are
+supported on your proxy host.
@item
@@ -4234,7 +4445,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}.
@@ -4421,9 +4632,8 @@ Abbreviation list expansion can be used to reduce typing long file names:
@lisp
@group
-(add-to-list
- 'directory-abbrev-alist
- '("^/xy" . "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))
+(add-to-list 'directory-abbrev-alist
+ '("^/xy" . "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))
@end group
@end lisp
diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi
index cc3c768fe6e..dbebbc36812 100644
--- a/doc/misc/trampver.texi
+++ b/doc/misc/trampver.texi
@@ -8,9 +8,10 @@
@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.5-pre
+@set trampver 2.5.0-pre
+@set trampurl https://www.gnu.org/software/tramp/
@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/url.texi b/doc/misc/url.texi
index 8d9b1024070..0304ff4b9f1 100644
--- a/doc/misc/url.texi
+++ b/doc/misc/url.texi
@@ -1312,8 +1312,6 @@ repeated visits do not require repeated domain lookups.
@end defopt
@defopt url-max-password-attempts
@end defopt
-@defopt url-temporary-directory
-@end defopt
@defopt url-show-status
@end defopt
@defopt url-confirmation-func
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}
generated by cgit v1.2.3 (git 2.39.1) at 2025-04-18 08:54:49 +0000