18 files changed, 657 insertions, 216 deletions

diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi
index d57d0b442f9..957cfbd9d8f 100644
--- a/doc/emacs/calendar.texi
+++ b/doc/emacs/calendar.texi
@@ -1005,7 +1005,7 @@ entries.
 * Adding to Diary::        Commands to create diary entries.
 * Special Diary Entries::  Anniversaries, blocks of dates, cyclic entries, etc.
 * Appointments::           Reminders when it's time to do something.
-* Importing Diary::        Converting diary events to/from other formats.
+* Diary Conversion::       Converting diary events to/from other formats.
 @end menu
 
 @node Format of Diary File
@@ -1549,71 +1549,287 @@ clock.  The command @kbd{M-x appt-add} adds entries to the appointment
 list without affecting your diary file.  You delete entries from the
 appointment list with @kbd{M-x appt-delete}.
 
-@node Importing Diary
+@node Diary Conversion
 @subsection Importing and Exporting Diary Entries
-@cindex importing diary entries
+@cindex diary import
+@cindex diary export
 
-  You can transfer diary entries between Emacs diary files and a
-variety of other formats.
+You can transfer diary entries between Emacs diary files and other
+formats.
 
-@vindex diary-outlook-formats
-  You can import diary entries from Outlook-generated appointment
-messages.  While viewing such a message in Rmail or Gnus, do @kbd{M-x
-diary-from-outlook} to import the entry.  You can make this command
-recognize additional appointment message formats by customizing the
-variable @code{diary-outlook-formats}.  Other mail clients can set
-@code{diary-from-outlook-function} to an appropriate value.
+@menu
+* Diary iCalendar Import::      Importing iCalendar data to the Diary.
+* Diary iCalendar Display::     Displaying iCalendar data without importing.
+* Diary iCalendar Export::      Exporting Diary entries to iCalendar.
+* Diary Outlook Import::        Importing Outlook appointments to the Diary.
+@end menu
+
+@node Diary iCalendar Import
+@subsubsection Importing iCalendar data as Diary Entries
+@cindex import iCalendar to diary
+
+@cindex iCalendar support in diary
+  @dfn{iCalendar} is an Internet standard format for exchanging calendar
+data.  Many calendar applications can export and import data in
+iCalendar format.  iCalendar data is also often sent as email
+attachments.  iCalendar data usually uses the @file{.ics} file
+extension, and is sent with the `text/calendar' @acronym{MIME} type in
+email.  (@xref{Mail Misc}, for more information on @acronym{MIME} and
+email attachments.)
+
+The @code{diary-icalendar} package allows you to make use of iCalendar
+data with the Emacs diary.  You can import and export data between
+iCalendar format and your Emacs diary file, and also display iCalendar
+data directly in the diary.
+
+The following commands will import iCalendar data to your diary file:
 
-@c FIXME the name of the RFC is hardly very relevant.
-@cindex iCalendar support
-  The icalendar package allows you to transfer data between your Emacs
-diary file and iCalendar files, which are defined in @cite{RFC
-2445---Internet Calendaring and Scheduling Core Object Specification
-(iCalendar)} (as well as the earlier vCalendar format).
-
-@c  Importing works for ordinary (i.e., non-recurring) events, but
-@c (at present) may not work correctly (if at all) for recurring events.
-@c Exporting of diary files into iCalendar files should work correctly
-@c for most diary entries.  This feature is a work in progress, so the
-@c commands may evolve in future.
-
-@findex icalendar-import-buffer
-  The command @code{icalendar-import-buffer} extracts
-iCalendar data from the current buffer and adds it to your
-diary file.  This function is also suitable for automatic extraction of
-iCalendar data; for example with the Rmail mail client one could use:
+@ftable @code
+@item diary-icalendar-import-file
+Imports an iCalendar file to an Emacs diary file.
+
+@item diary-icalendar-import-buffer
+Imports iCalendar data from the current buffer to an Emacs diary file.
+@end ftable
+
+@code{diary-icalendar-import-buffer} is also suitable for importing
+iCalendar data from email attachments.  For example, with the Rmail mail
+client, you could use:
 
 @example
-(add-hook 'rmail-show-message-hook 'icalendar-import-buffer)
+(add-hook 'rmail-show-message-hook #'diary-icalendar-import-buffer)
 @end example
 
-@findex icalendar-import-file
-  The command @code{icalendar-import-file} imports an iCalendar file
-and adds the results to an Emacs diary file.  For example:
+Diary import depends on a number of user-customizable variables, which
+are in the @code{diary-icalendar-import} customization group.  You can
+review and customize these variables with @kbd{M-x customize-group}.
+@xref{Customization Groups}.
+
+iCalendar data is grouped into @dfn{components} which represent calendar
+events (the VEVENT component), tasks (VTODO), and other text data
+(VJOURNAL).  Because these components contain different types of data,
+they are imported by different functions, determined by the following
+variables:
+
+@vtable @code
+@item diary-icalendar-vevent-format-function
+Function to format VEVENT components for the diary.
+
+@item diary-icalendar-vjournal-format-function
+Function to format VJOURNAL components for the diary.
+
+@item diary-icalendar-vtodo-format-function
+Function to format VTODO components for the diary.
+@end vtable
+
+You can customize the format of the imported diary entries by writing
+your own formatting functions.  It is convenient (but not required) to
+express such functions as templates called @dfn{skeletons}.
+@ifinfo
+@xref{Top, Autotyping, The Autotype Manual, autotype}, for more about
+skeletons.
+@end ifinfo
+
+For example, suppose you only want to import the date, time, summary,
+and location of each calendar event, and to write them on a single line
+like:
 
 @example
-(icalendar-import-file "/here/is/calendar.ics"
-                       "/there/goes/ical-diary")
+2025/11/11 Summary @@ Some Location
 @end example
 
 @noindent
-You can use an @code{#include} directive to add the import file contents
-to the main diary file, if these are different files.
-@iftex
-@xref{Fancy Diary Display,,, emacs-xtra, Specialized Emacs Features}.
-@end iftex
-@ifnottex
-@xref{Fancy Diary Display}.
-@end ifnottex
+Then you could write the import formatting function as a skeleton and
+set it to the value of @code{diary-icalendar-vevent-format-function} as
+follows:
+
+@lisp
+@group
+(require 'skeleton)
+
+(defun simple-vevent (_)
+  "Format a VEVENT summary and location on a single line"
+  (skeleton-insert
+    '(nil
+      ical-start-to-end & " " & ical-summary & " "
+      (when ical-location "@@ ") & ical-location "\n")))
+
+(setopt diary-icalendar-vevent-format-function #'simple-vevent)
+@end group
+@end lisp
+
+The variables @code{ical-start-to-end}, @code{ical-summary} and
+@code{ical-location} in this example are dynamically bound to
+appropriate values when the skeleton is called.  See the docstring of
+@code{diary-icalendar-vevent-format-function} for more information.
+
+Any errors encountered during import will be reported in a buffer named
+@file{*icalendar-errors*}.  You can review these errors with the
+@code{next-error} command.  @xref{Compilation Mode}.  If you regularly
+need to import malformed iCalendar data, there are several hooks
+available for this purpose; see the @code{icalendar-parser}
+customization group.
+
+@node Diary iCalendar Display
+@subsubsection Displaying iCalendar entries in the Diary
+@cindex display iCalendar in diary
+
+If you primarily store your calendar data outside of Emacs, but still
+want to see it in the Emacs calendar and diary, you can do so by
+including an iCalendar file from your diary file.
+
+Suppose, for example, that you download your calendar from an
+external server to a file called @file{Appointments.ics}.  Then you can
+include this file in your diary by writing a line like
 
+@example
+#include "path/to/Appointments.ics"
+@end example
+
+@noindent
+in your diary file.  You must also set up some hooks to display the
+data in that file as diary entries and mark them in the calendar:
+
+@lisp
+@group
+(add-hook 'diary-mark-entries-hook
+          #'diary-mark-included-diary-files)
+(add-hook 'diary-nongregorian-marking-hook
+          #'diary-icalendar-mark-entries)
+(add-hook 'diary-list-entries-hook
+          #'diary-include-other-diary-files)
+(add-hook 'diary-nongregorian-listing-hook
+          #'diary-icalendar-display-entries)
+@end group
+@end lisp
+
+@noindent
+Events, tasks, and journal entries in @file{Appointments.ics} will then show
+up on the appropriate days when you display the diary from the calendar.
+@xref{Displaying the Diary}.
+
+The advantage of doing this is that you don't need to synchronize the
+data between the calendar server and your diary file.  This is simpler
+and more reliable than regularly importing and exporting between diary
+and iCalendar format.
+
+@findex diary-icalendar-mailcap-viewer
+  You can also display iCalendar attachments in email messages
+without importing them to your diary file using the function
+@code{diary-icalendar-mailcap-viewer}.  You can add this function, for
+example, to the variable @code{mailcap-user-mime-data}; see its docstring
+for more information.
+
+Displaying iCalendar entries uses the same infrastructure as importing
+them, so customizing the import format will also change the format of
+the displayed entries.  @xref{Diary iCalendar Import}.
+
+@node Diary iCalendar Export
+@subsubsection Exporting Diary Entries to iCalendar
+@cindex export diary to iCalendar
+
+The following commands will export diary entries in iCalendar format:
+
+@ftable @code
+@item diary-icalendar-export-file
+Exports a diary file to iCalendar format.
+
+@item diary-icalendar-export-region
+Exports a region of diary text to iCalendar format.
+@end ftable
+
+iCalendar export depends on a number of user-customizable variables, which
+are in the @code{diary-icalendar-export} customization group.  You can
+review and customize these variables with @kbd{M-x customize-group}.
+@xref{Customization Groups}.
+
+Exporting diary entries to iCalendar requires you to respect certain
+conventions in your diary, so that iCalendar properties can be parsed
+from your diary entries.
+
+By default, the exporter will use the first line of the entry (after the
+date and time) as the iCalendar summary and the rest of the entry as its
+iCalendar description.  Other iCalendar properties can also be encoded in
+the entry on separate lines, like this:
+
+@example
+@group
+2025/11/11 Bender's birthday bash
+  Location: Robot House
+  Attendees:
+    Fry <philip.fry@@mars.edu>
+    Günter <guenter@@mars.edu>
+@end group
+@end example
+
+@noindent
+This format matches the format produced by the default import
+functions.
+
+@vindex diary-icalendar-address-regexp
+@vindex diary-icalendar-class-regexp
+@vindex diary-icalendar-description-regexp
+@vindex diary-icalendar-location-regexp
+@vindex diary-icalendar-organizer-regexp
+@vindex diary-icalendar-status-regexp
+@vindex diary-icalendar-summary-regexp
+@vindex diary-icalendar-todo-regexp
+@vindex diary-icalendar-uid-regexp
+@vindex diary-icalendar-url-regexp
+If you customize the import format, or you want to export diary entries
+in a different format, you will need to customize the export variables
+to detect the format of your diary entries.  The most common iCalendar
+properties are parsed from diary entries using regular expressions.  See
+the variables named @code{diary-icalendar-*-regexp} in the
+@code{diary-icalendar-export} customization group to modify how these
+properties are parsed.
+
+@vindex diary-icalendar-other-properties-parser
+  If you need to export other iCalendar properties, or do more
+complicated parsing, you can define a function to do so and set it as
+the value of the variable @code{diary-icalendar-other-properties-parser};
+see its docstring for details.
+
+@vindex diary-icalendar-export-linewise
+  By default, the exporter assumes that each diary entry represents a
+single iCalendar event.  If you like to keep your diary in a
+one-entry-per-day format, with different events on continuation
+lines within the same entry, you can still export such entries as
+distinct iCalendar events.  To do this, set the variable
+@code{diary-icalendar-export-linewise} to a non-nil value.
+
+For example, after setting this variable, an entry like:
+
+@example
+@group
+2025-05-03
+  9AM Lab meeting
+    Günter to present on new assay
+  Start experiment A
+  12:30-1:30PM Lunch with Phil
+  16:00 Experiment A finishes; move to freezer
+@end group
+@end example
+
+@noindent
+will be exported as four events, each on the same day, but with
+different start times (except for the second event, ``Start experiment
+A'', which has no start time).  See the docstring of
+@code{diary-icalendar-export-linewise} for more information.
+
+@node Diary Outlook Import
+@subsubsection Importing Outlook appointments as Diary Entries
+@cindex diary outlook import
+
+@vindex diary-outlook-formats
+@vindex diary-from-outlook-function
+  You can also import diary entries from Outlook-generated appointment
+messages.  While viewing such a message in Rmail or Gnus, do @kbd{M-x
+diary-from-outlook} to import the entry.  You can make this command
+recognize additional appointment message formats by customizing the
+variable @code{diary-outlook-formats}.  Other mail clients can set
+@code{diary-from-outlook-function} to an appropriate value.
 
-@findex icalendar-export-file
-@findex icalendar-export-region
-@cindex export diary
-  Use @code{icalendar-export-file} to interactively export an entire
-Emacs diary file to iCalendar format.  To export only a part of a diary
-file, mark the relevant area, and call @code{icalendar-export-region}.
-In both cases, Emacs appends the result to the target file.
 
 @node Daylight Saving
 @section Daylight Saving Time
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 7663e2b21df..b2fcb3c489f 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1615,24 +1615,30 @@ your preference, such as @code{ws-butler-mode}.
 @cindex per-connection local variables
 
   Most of the variables reflect the situation on the local machine.
-Often, they must use a different value when you operate in buffers
-with a remote default directory.  Think about the behavior when
-calling @code{shell} -- on your local machine, you might use
-@file{/bin/bash} and rely on termcap, but on a remote machine, it may
-be @file{/bin/ksh} and terminfo.
-
-  This can be accomplished with @dfn{connection-local variables}.
-Directory and file local variables override connection-local
-variables.  Unsafe connection-local variables are handled in the same
-way as unsafe file-local variables (@pxref{Safe File Variables}).
+Often, they must use a different value when you operate in buffers with
+a remote default directory.  Think about the behavior when calling
+@code{shell} --- on your local machine, you might use @file{/bin/bash}
+and rely on termcap, but on a remote machine, it may be @file{/bin/ksh}
+and terminfo.
+
+  This can be accomplished with @dfn{connection-local variables}.  Such
+variables are declared depending on the value of
+@code{default-directory} of the current buffer.  When a buffer has a
+remote @code{default-directory}, and there exist a connection-local
+variable which matches @code{default-directory}, this alternative value
+of the variable is used.  Directory and file local variables override
+connection-local variables.  Unsafe connection-local variables are
+handled in the same way as unsafe file-local variables (@pxref{Safe File
+Variables}).
 
 @findex connection-local-set-profile-variables
 @findex connection-local-set-profiles
-  Connection-local variables are declared as a group of
-variables/value pairs in a @dfn{profile}, using the
+  Connection-local variables are declared as a group of variables/value
+pairs in a @dfn{profile}, using the
 @code{connection-local-set-profile-variables} function.  The function
-@code{connection-local-set-profiles} activates profiles for a given
-criteria, identifying a remote machine:
+@code{connection-local-set-profiles} declares profiles for a given
+criteria (the first argument), identifying a remote machine with respect
+to @code{default-directory} of the current buffer:
 
 @example
 (connection-local-set-profile-variables 'remote-terminfo
@@ -1654,12 +1660,46 @@ criteria, identifying a remote machine:
 
   This code declares three different profiles, @code{remote-terminfo},
 @code{remote-ksh}, and @code{remote-bash}.  The profiles
-@code{remote-terminfo} and @code{remote-ksh} are applied to all
-buffers which have a remote default directory matching the regexp
-@code{"remotemachine"} as host name.  Such a criteria can also
-discriminate for the properties @code{:protocol} (this is the Tramp
-method) or @code{:user} (a remote user name).  The @code{nil} criteria
-matches all buffers with a remote default directory.
+@code{remote-terminfo} and @code{remote-ksh} are applied to all buffers
+which have a remote @code{default-directory} matching the string
+@code{"remotemachine"} as host name.
+
+  Criteria, the first argument of @code{connection-local-set-profiles},
+specifies, how the profiles match @code{default-directory}.  It is a
+plist identifying a connection and the application using this
+connection.  Property names might be @code{:application},
+@code{:protocol}, @code{:user} and @code{:machine}.  The property value
+of @code{:application} is a symbol, all other property values are
+strings.  In general the symbol @code{tramp} should be used as
+@code{:application} value.  Some packages use a different
+@code{:application} (for example @code{eshell} or @code{vc-git}); they
+say it in their documentation then.  All properties are optional.
+
+  The other properties are used for checking @code{default-directory}.
+The propertiy @code{:protocol} is used for the method a remote
+@code{default-directory} uses, the property
+@code{:user} is the remote user name, and the property @code{:machine}
+is the remote host name.  All checks are performed via
+@code{string-equal}.  The @code{nil} criteria matches all buffers
+with a remote default directory.
+
+  Connection-local variables are not activated by default.  A package
+which uses connection-local variables must activate them for a given
+buffer, specifying for which @code{:application} it uses them.
+@xref{Applying Connection Local Variables,,, elisp, The Emacs Lisp
+Reference Manual}, for details.
+
+  After the above definition of profiles and their activation, any
+connection made by Tramp to the @samp{remotemachine} system will use
+
+@itemize
+@item @code{t} as the connection-specific value of @code{system-uses-terminfo},
+@item @samp{dumb-emacs-ansi} as the connection-specific value of
+@code{comint-terminfo-terminal},
+@item @samp{/bin/ksh} as the connection-specific value of as
+@code{shell-file-name},
+@item @samp{-c} as the connection-specific value of @code{shell-command-switch}.
+@end itemize
 
   Be careful when declaring different profiles with the same variable,
 and setting these profiles to criteria which could match in parallel.
@@ -3098,30 +3138,33 @@ elisp, The Emacs Lisp Reference Manual}.
   If the directory specified by @code{user-lisp-directory}, defaulting
 to @file{~/.config/emacs/user-lisp/} or @file{~/.emacs.d/user-lisp/},
 exists, then at startup Emacs will prepare Lisp files within that
-directory for use in the session.  Emacs does the following things:
+directory for use in the session.  Specifically, Emacs does the
+following:
 
 @itemize
 @item
 Gather and activate autoload cookies.  This means that you can use
 autoloaded commands and other entry points for the files in your
 @code{user-lisp-directory} without explicitly loading any of the
-files in your initialization file. (@pxref{Autoload,,, elisp, The
-Emacs Lisp Reference Manual}.)
+files in your initialization file.  @xref{Autoload,,, elisp, The
+Emacs Lisp Reference Manual}.
 @item
-Byte-compile all files, and if supported on your system, natively
-compile them too.  This speeds up the execution of the code in the
-files when they are loaded.  (@pxref{Byte Compilation,,, elisp, The
-Emacs Lisp Reference Manual}.)
+Byte-compile all the files (@pxref{Byte Compilation,,, elisp, The Emacs
+Lisp Reference Manual}), and if supported by your build of Emacs,
+compile them to native code as well (@pxref{Native Compilation,,, elisp,
+The Emacs Lisp Reference Manual}).  This speeds up the execution of the
+code in those files when they are loaded and when they are executed
+later.
 @item
 Adjust @code{load-path} such that all the files can be loaded and
-autoloaded in the usual ways.  (@pxref{Library Search,,, elisp, The
-Emacs Lisp Reference Manual}.)
+autoloaded in the usual ways.  @xref{Library Search,,, elisp, The
+Emacs Lisp Reference Manual}.
 @end itemize
 
-  The User Lisp directory is processed before loading the @ref{Init
-File} file.  Therefore any customizations to the user options discussed
-below must be made in your early init file (@pxref{Early Init File}) in
-order to have any effect.
+  The User Lisp directory is processed before loading your init file
+(@pxref{Init File}).  Therefore any customizations to the user
+options discussed below must be made in your early init file
+(@pxref{Early Init File}) in order to have any effect.
 
 @vindex user-lisp-ignored-directories
 @vindex user-lisp-auto-scrape
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 49a3ba57b1c..05ced62dd9c 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -1020,7 +1020,14 @@ The Diary
 * Adding to Diary::        Commands to create diary entries.
 * Special Diary Entries::  Anniversaries, blocks of dates, cyclic entries, etc.
 * Appointments::           Reminders when it's time to do something.
-* Importing Diary::        Converting diary events to/from other formats.
+* Diary Conversion::       Converting diary events to/from other formats.
+
+Diary Conversion
+
+* Diary iCalendar Import::      Importing iCalendar data to the Diary.
+* Diary iCalendar Display::     Displaying iCalendar data without importing.
+* Diary iCalendar Export::      Exporting Diary entries to iCalendar.
+* Diary Outlook Import::        Importing Outlook appointments to the Diary.
 
 @ifnottex
 More advanced features of the Calendar and Diary
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 567c1492518..a9bcee0b060 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1835,7 +1835,8 @@ the start of the @var{n}th previous file.
 
 @findex diff-hunk-kill
 @item M-k
-Kill the hunk at point (@code{diff-hunk-kill}).
+Kill the hunk at point (@code{diff-hunk-kill}).  If the region is
+active, kills all hunks the region overlaps.
 
 @findex diff-file-kill
 @item M-K
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index aebe31b478e..1d54af130a9 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2323,6 +2323,11 @@ configuration (if any), excluding the ``ignored'' files from the output.
 It has some performance optimizations for listing the files with some of
 the popular VCS systems (currently Git and Mercurial).
 
+@findex project-remember-projects-under
+It also uses a time-based cache.  If the mode line shows stale project
+information, you can type @kbd{M-x project-remember-projects-under RET}
+to refresh the stale cached info.
+
 @defopt project-vc-include-untracked
 By default, files which are neither registered with nor ignored by the
 VCS are considered part of the project.  Customize this variable to nil
@@ -2569,12 +2574,13 @@ files, and build a database of these references.  A backend can then
 access this database whenever it needs to list or look up references.
 The Emacs distribution includes @command{etags}, a command for tagging
 identifier definitions in programs, which supports many programming
-languages and other major modes, such as HTML, by extracting
-references into @dfn{tags tables}.  @xref{Create Tags Table}.  Major
-modes for languages supported by @command{etags} can use tags tables
-as basis for their backend.  (One disadvantage of this kind of backend
-is that tags tables need to be kept reasonably up to date, by
-rebuilding them from time to time.)
+languages and other major modes, such as HTML, by extracting references
+into @dfn{tags tables}.  Major modes for languages supported by
+@command{etags} can use tags tables as basis for their backend.  Enable
+@code{etags-regen-mode} to have tags tables generated across the current
+project for supported file types and updated automatically upon edit.
+Alternatively, you can build the table manually to control the set of
+files and when it is updated, see @ref{Create Tags Table}.
 @end enumerate
 
 @menu
@@ -2648,6 +2654,9 @@ to always prompt, customize @code{xref-prompt-for-identifier} to
 usual minibuffer completion commands (@pxref{Completion}), with the
 known identifier names being the completion candidates.
 
+  It uses the current Xref backend, and will signal an error when there
+is none configured, with some recommendations.
+
 @kindex C-x 4 .
 @findex xref-find-definitions-other-window
 @kindex C-x 5 .
@@ -3028,7 +3037,9 @@ writes the tags to a @dfn{tags table file}, or @dfn{tags file} in
 short.  The conventional name for a tags file is @file{TAGS}@.
 @xref{Create Tags Table}.  (It is also possible to create a tags table
 by using one of the commands from other packages that can produce such
-tables in the same format.)
+tables in the same format.)  If you enable the @code{etags-regen-mode}
+global minor mode, Emacs will generate and update the tags tables
+automatically as needed.
 
   Emacs uses the tags tables via the @code{etags} package as one of
 the supported backends for @code{xref}.  Because tags tables are
@@ -3310,6 +3321,10 @@ You should update a tags table when you define new tags that you want
 to have listed, or when you move tag definitions from one file to
 another, or when changes become substantial.
 
+  If the @code{etags-regen-mode} minor mode, described below, is
+enabled, Emacs will automatically keep the tags tables up-to-date as
+needed.
+
   You can make a tags table @dfn{include} another tags table, by
 passing the @samp{--include=@var{file}} option to @command{etags}.  It
 then covers all the files covered by the included tags file, as well
@@ -3418,11 +3433,11 @@ Command-line options to pass to the program which regenerates tags
 tables.
 
 @item etags-regen-ignores
-List of glob patterns which specify files to ignore when regenerating
-tags tables.
+List of glob wildcard patterns which specify files to ignore when
+regenerating tags tables.
 @end vtable
 
-@cindex tags-reset-tags-tables
+@findex tags-reset-tags-tables
   If you select a tags table manually, with @kbd{M-x visit-tags-table}
 (@pxref{Select Tags Table}), @code{etags-regen-mode} effectively
 disables itself: it will no longer automatically create and update
@@ -3607,6 +3622,12 @@ to the first directory that contains a file named @file{TAGS}
 encountered when recursively searching upward from the default
 directory.
 
+  If you enable the @code{etags-regen-mode} global minor mode, it will
+automatically find and visit the tags table file when needed.  If you
+then invoke @code{visit-tags-table} manually to select a tags table,
+@code{etags-regen-mode} will disable automatic regeneration of the tags
+table.  @xref{Create Tags Table}.
+
 @vindex tags-file-name
   Emacs does not actually read in the tags table contents until you
 try to use them; all @code{visit-tags-table} does is store the file
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index e6432678c62..fdb0822e85c 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -454,6 +454,17 @@ case, Emacs retrieves packages from this archive via ordinary file
 access.  Such local archives are mainly useful for testing.
 @end defopt
 
+@cindex suggestions
+@findex package-autosuggest
+@findex package-autosuggest-mode
+  Emacs has a built-in database of suggested packages for certain file
+types.  If Emacs opens a file with no specific mode, you can use the
+@code{package-autosuggest} command to install the recommended packages
+from ELPA.  After enabling @code{package-autosuggest-mode}, Emacs will
+display a clickable hint in the mode-line if it there is a suggested
+package.  Using the @code{package-autosuggest-style} user option, you
+can adjust how Emacs presents the hint to install a package.
+
 @anchor{Package Signing}
 @cindex package security
 @cindex package signing
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index bd31798d431..0583179ed31 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2778,12 +2778,12 @@ To test the signal handler, you can make Emacs send a signal to itself:
 @end smallexample
 
 @cindex @code{sleep-event} event
-@item (sleep-event @var{sleep-wake})
-This event is injected when the device Emacs is running on enters or
-leaves the sleep state.  A non-@code{nil} @var{sleep-wake} indicates
-entering the sleep state.
+@item (sleep-event @var{state})
+This event is injected when the device Emacs is running on is about to
+enter a sleep state, or has just awoken from one.  @var{state} will be
+the symbol @code{pre-sleep} or @code{post-wake}.
 
-This is implemented only on GNU/Linux.
+This is implemented on GNU/Linux, macOS, and MS-Windows.
 
 @cindex @code{language-change} event
 @item language-change
@@ -4062,7 +4062,8 @@ definition to find the actual event.
 user signals like @code{sigusr1} are normally handled in this way.
 The keymap which defines how to handle special events---and which
 events are special---is in the variable @code{special-event-map}
-(@pxref{Controlling Active Maps}).
+(@pxref{Controlling Active Maps}).  @xref{Misc Events}, for more details
+about these and other special events.
 
 @defun insert-special-event
 @cindex inserting special events
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index a4776030cf2..85e13952cfb 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1493,25 +1493,27 @@ argument:
 @subsection The @code{cond*} macro
 @findex cond*@r{, a macro}
 
-  The @code{cond*} macro is an alternative to @code{pcase}, and supports
-the same functionality, but using syntax that some might find less
-cryptic.
+  You can use the @code{cond*} macro as an alternative to @code{pcase}
+if you find @code{pcase}'s syntax too cryptic.  In addition,
+@code{cond*} offers some new forms of control flow that aren't related
+to being an alternative to @code{pcase}.
 
 @defmac cond* &rest clauses
 The @code{cond*} macro is an extended form of the traditional
 @code{cond}.  A @code{cond*} expression contains a series of
-@var{clauses}, each of which can use @code{bind*} to specify binding
-variables, use @code{match*} to specify matching a pattern as a
-condition, or specify an expression as a condition to evaluate as a
-test.
+@var{clauses}, each of which can use @code{bind*} or @code{bind-and*} to
+specify binding variables, use @code{match*} or @code{pcase*} to specify
+matching a pattern as a condition, or specify an expression as a
+condition to evaluate as a test.
 
 Each clause normally has the form @w{@code{(@var{condition}
 @var{body}@dots{})}}.
 
 @var{condition} can be a Lisp expression, as in @code{cond}
 (@pxref{Conditionals}).  Or it can be @w{@code{(bind*
-@var{bindings}@dots{})}} or @w{@code{(match* @var{pattern}
-@var{datum})}}.
+@var{bindings}@dots{})}}, @w{@code{(match* @var{pattern} @var{datum})}},
+@w{@code{(bind-and* @var{bindings}@dots{})}} or @w{@code{(pcase*
+@var{pattern} @var{datum})}}
 
 @findex bind*
 @code{(bind* @var{bindings}@dots{})} means to bind @var{bindings} (like
@@ -1536,21 +1538,22 @@ bind to the parts of @var{datum} that they match.
 @code{(pcase* @var{pattern} @var{datum})} works in the same way except it
 uses the Pcase syntax for @var{pattern}.
 
-@code{bind*}, @code{match*}, and @code{pcase*} normally bind their bindings over
-the execution of the whole containing clause.  However, if the clause is
-written to specify ``non-exit'', the clause's bindings cover the whole
-rest of the @code{cond*}.
+@code{match*}, and @code{pcase*} normally bind their bindings over the
+execution of the whole containing clause.  However, if the clause is
+written to specify ``non-exit'' (see below), the clause's bindings cover
+the whole rest of the @code{cond*}.
 
 When a clause's condition is true, and it exits the @code{cond*} or is
 the last clause, the value of the last expression in the clause's body
 becomes the return value of the @code{cond*} construct.
 
-@subheading Non-exit clause
+@subheading Non-exit clauses
 
-If a clause has only one element, or if its first element is @code{t},
-or if it ends with the keyword @code{:non-exit}, then this clause never
-exits the @code{cond*} construct.  Instead, control falls through to the
-next clause (if any).  The bindings made in @var{condition} for the
+If a clause has only one element, or if its first element is @code{t} or
+a @code{bind*} form, or if it ends with the keyword @code{:non-exit},
+then this clause never exits the @code{cond*} construct.  Instead,
+control falls through to the next clause (if any).  Except for a
+@code{bind-and*} clause, the bindings made in @var{condition} for the
 @var{body} of the non-exit clause are passed along to the rest of the
 clauses in this @code{cond*} construct.
 
@@ -2344,7 +2347,9 @@ the other usual filtering mechanisms say it should.  @xref{Error Debugging}.
 The macro @code{condition-case-unless-debug} provides another way to
 handle debugging of such forms.  It behaves exactly like
 @code{condition-case}, unless the variable @code{debug-on-error} is
-non-@code{nil}, in which case it does not handle any errors at all.
+non-@code{nil}, in which case it causes Emacs to enter the debugger
+before executing any applicable handler.  (The applicable handler, if
+any, will still run when the debugger exits.)
 @end defmac
 
   Once Emacs decides that a certain handler handles the error, it
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 4211b435db5..464c0badc36 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2243,6 +2243,9 @@ means hide the excess parts of @var{string} with a @code{display} text
 property (@pxref{Display Property}) showing the ellipsis, instead of
 actually truncating the string.
 
+See also the function @code{truncate-string-pixelwise} for pixel-level
+resolution.
+
 @example
 @group
 (truncate-string-to-width "\tab\t" 12 4)
@@ -2440,6 +2443,37 @@ non-@code{nil}, use any face remappings (@pxref{Face Remapping}) from
 that buffer when computing the width of @var{string}.
 @end defun
 
+@defun truncate-string-pixelwise string max-pixels &optional buffer ellipsis ellipsis-pixels
+This is a convenience function that uses @code{window-text-pixel-size}
+to truncate @var{string} to @var{max-pixels} pixels.  Caveat: if you
+call this function to measure the width of a string with embedded
+newlines, it will then return the width of the widest substring that
+does not include newlines.  The meaning of this result is the widest
+line taken by the string if inserted into a buffer.  If @var{buffer} is
+non-@code{nil}, use any face remappings (@pxref{Face Remapping}) from
+that buffer when computing the width of @var{string}.
+
+If @var{ellipsis} is non-@code{nil}, it should be a string which will
+replace the end of @var{string} when it is truncated.  In this case,
+more characters will be removed from @var{string} to free enough space
+for @var{ellipsis} to fit within @var{max-pixels} pixels.  However, if
+the pixel width of @var{string} is less than the pixel width of
+@var{ellipsis}, @var{ellipsis} will not be appended to the result.  If
+@var{ellipsis} is non-@code{nil} and not a string, it stands for the
+value returned by the function @code{truncate-string-ellipsis},
+described above.
+
+If @var{ellipsis-pixels} is non-@code{nil} and @var{ellipsis} is
+non-@code{nil}, it should be the number of pixels of @var{ellipsis} that
+you should precompute using @code{string-pixel-width}, specifying the
+same buffer.  This is useful to avoid the cost of recomputing this value
+repeatedly when you have many strings to truncate using the same
+ellipsis string.
+
+See also the function @code{truncate-string-to-width} for
+character-level resolution.
+@end defun
+
 @defun line-pixel-height
 This function returns the height in pixels of the line at point in the
 selected window.  The value includes the line spacing of the line
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index c64ec3ea715..5444cea7fa9 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -674,6 +674,7 @@ variable; these two uses of a symbol are independent and do not
 conflict.  (This is not the case in some dialects of Lisp, like
 Scheme.)
 
+@cindex internal functions, naming conventions
   By convention, if a function's symbol consists of two names
 separated by @samp{--}, the function is intended for internal use and
 the first part names the file defining the function.  For example, a
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 2214a30c170..13a8ec46a8a 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -5026,7 +5026,7 @@ should return the @var{offset} to use to indent @var{arg} itself.
 @item
 @code{:elem}, in which case the function should return either the offset
 to use to indent function arguments (if @var{arg} is the symbol
-@code{arg}) or the basic indentation step (if @var{arg} is the symbol
+@code{args}) or the basic indentation step (if @var{arg} is the symbol
 @code{basic}).
 @item
 @code{:list-intro}, in which case @var{arg} is a token and the function
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index f5ca6efa21b..ccc0f69a12d 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -35,6 +35,7 @@ terminal and the screen.
 * Session Management::  Saving and restoring state with X Session Management.
 * Desktop Notifications:: Desktop notifications.
 * System Taskbar::      Controlling system GUI taskbar features.
+* System Sleep::        Block system sleep and process sleep events.
 * File Notifications::  File notifications.
 * Dynamic Libraries::   On-demand loading of support libraries.
 * Security Considerations:: Running Emacs in an unfriendly environment.
@@ -2285,7 +2286,7 @@ be protected by wrapping the timer function body with
 
 @lisp
 @group
-(ignore-error 'remote-file-error
+(ignore-error remote-file-error
   @dots{})
 @end group
 @end lisp
@@ -3493,6 +3494,75 @@ Examples of system taskbar functions:
 @end group
 @end lisp
 
+@node System Sleep
+@section Block System Sleep and Process Sleep Events
+@cindex system sleep
+@cindex mode, system sleep
+
+@defun system-sleep-block-sleep &optional why allow-display-sleep
+This function blocks the system from entering its idle sleep state.
+
+It returns a token that must be passed to
+@code{system-sleep-unblock-sleep} to unblock this specific block (other
+sleep blocks may be simultaneously in force for other purposes).
+Otherwise, it returns @code{nil} if the sleep blocking fails.
+
+@var{why} is a string and, when non-@code{nil}, is used to identify the
+sleep block as it may appear on the system's inspectable block lists.
+It defaults to @samp{Emacs}.
+
+If @var{allow-display-sleep} is non-@code{nil}, allow the display to
+sleep.  By default, the display is kept active.
+
+Note that when the Emacs process terminates, blocks are released on all
+platforms.
+@end defun
+
+@defun system-sleep-unblock-sleep token
+This function unblocks the sleep block associated with @var{token}.  It
+returns non-@code{nil} on success, otherwise it returns @code{nil}.
+@end defun
+
+@defmac with-system-sleep-block (&optional why allow-display-sleep) body@dots{}
+This is a convenience macro that lets you wrap the forms in @var{body}
+with a sleep block that is unblocked for you when @var{body} completes.
+This guarantees that the system will never go to sleep while @var{body}
+executes.  The arguments have the same meaning as in
+@code{system-sleep-block-sleep}, above.
+@end defmac
+
+@defun system-sleep-sleep-blocked-p
+This predicate function returns non-@code{nil} if there are any
+active @code{system-sleep} blocks, otherwise it returns @code{nil}.
+@end defun
+
+@defun system-sleep-unblock-all-sleep-blocks
+This function unblocks all active sleep blocks.  It is unlikely that you
+will need to call this function.
+@end defun
+
+@defopt system-sleep-event-functions
+When the system is about to enter a sleep state or after it wakes from
+one, each function on this abnormal hook is called with one argument,
+@var{event}, a sleep event.  Its state can be retrieved via
+@samp{@code{(sleep-event-state event)}}.  State will be one of the
+symbols @code{pre-sleep} or @code{post-wake}.
+
+Handling @code{pre-sleep} events should be done as fast as possible and
+avoid user prompting.  Systems often grant a very short pre-sleep
+processing interval, typically ranging between 2 and 5 seconds.  The
+system may sleep even if your processing is not complete, so be sure you
+do as little as possible.  For example, your function could close active
+connections or serial ports.
+
+Handling @code{post-wake} events offers more leeway.  Use this, for
+example, to reestablish connections.
+
+Note: Your code, or the functions it calls, should not raise any signals
+or all hooks will be halted.  You can wrap your code in a
+@code{condition-case} block (@pxref{Errors}).
+@end defopt
+
 @node File Notifications
 @section Notifications on File Changes
 @cindex file notifications
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 4de739aa915..afee255346c 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -1110,9 +1110,9 @@ instead of the default @code{equal}.
 @cindex sequences, intersection of
 @cindex intersection of sequences
   This function returns a copy of @var{sequence1} from which the
-elements that appear in @var{sequence2} where removed.  If the optional
-argument @var{function} is non-@code{nil}, it is a function of two
-arguments to use to compare elements instead of the default
+elements that do not appear in @var{sequence2} were removed.  If the
+optional argument @var{function} is non-@code{nil}, it is a function of
+two arguments to use to compare elements instead of the default
 @code{equal}.
 
 @example
@@ -1125,10 +1125,11 @@ arguments to use to compare elements instead of the default
 
 
 @defun seq-difference sequence1 sequence2 &optional function
-  This function returns a list of the elements that appear in
-@var{sequence1} but not in @var{sequence2}.  If the optional argument
-@var{function} is non-@code{nil}, it is a function of two arguments to
-use to compare elements instead of the default @code{equal}.
+  This function returns a copy of @var{sequence1} from which the
+elements that appear in @var{sequence2} were removed.  If the optional
+argument @var{function} is non-@code{nil}, it is a function of two
+arguments to use to compare elements instead of the default
+@code{equal}.
 
 @example
 @group
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 44be529d562..d073d3ffe2f 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -281,6 +281,17 @@ another string, alter a constant string in the program, or even raise
 an error.  To obtain a string that you can safely mutate, use
 @code{copy-sequence} on the result.
 
+If you need to create a string made from @var{n} copies of a given
+source string @var{source}, you can use @code{concat} as follows:
+
+@lisp
+  (apply #'concat (make-list @var{n} @var{source}))
+@end lisp
+
+@noindent
+This uses the fact that @code{concat} can take any kind of sequence as
+its arguments.
+
 For information about other concatenation functions, see the
 description of @code{mapconcat} in @ref{Mapping Functions},
 @code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 29a272eec92..e89b28eb0c0 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -617,6 +617,8 @@ float-pi
 
 @node Tips for Defining
 @section Tips for Defining Variables Robustly
+@cindex variables, naming conventions
+@cindex naming conventions, variables
 
   When you define a variable whose value is a function, or a list of
 functions, use a name that ends in @samp{-function} or
@@ -659,6 +661,7 @@ The value is a whole shell command.
 @item @dots{}-switches
 The value specifies options for a command.
 
+@cindex internal variables, naming conventions
 @item @var{prefix}--@dots{}
 The variable is intended for internal use and is defined in the file
 @file{@var{prefix}.el}.  (Emacs code contributed before 2018 may
@@ -2653,6 +2656,19 @@ This macro returns the connection-local value of @var{symbol} for
 
 If @var{symbol} does not have a connection-local
 binding, the value is the default binding of the variable.
+
+The difference to @code{with-connection-local@{-application@}-variables}
+is, that @code{symbol} is not set buffer-local.  A typical usage pattern
+is to use only the the connection value of a variable if it exists, and
+not to use its default value otherwise (using @code{my-app-variable}
+initialized above):
+
+@lisp
+(if (connection-local-p my-app-variable 'my-app)
+    (connection-local-value my-app-variable 'my-app)
+  ;; Something else.
+  )
+@end lisp
 @end defmac
 
 @defvar enable-connection-local-variables
diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 59685087ae8..5b302c883ad 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -64,7 +64,7 @@ another.  An overview of D-Bus can be found at
 * Alternative Buses::           Alternative buses and environments.
 * Errors and Events::           Errors and events.
 * Monitoring Messages::         Monitoring messages.
-* Inhibitor Locks::             Inhibit system shutdowns and sleep states.
+* File Descriptors::            Handle file descriptors.
 * Index::                       Index including concepts, functions, variables.
 
 * GNU Free Documentation License:: The license for this documentation.
@@ -1212,7 +1212,7 @@ which carries the input parameters to the object owning the method to
 be called, and a reply message returning the resulting output
 parameters from the object.
 
-@defun dbus-call-method bus service path interface method &optional :timeout timeout :authorizable auth &rest args
+@defun dbus-call-method bus service path interface method &optional :timeout timeout :authorizable auth :keep-fd &rest args
 @anchor{dbus-call-method}
 This function calls @var{method} on the D-Bus @var{bus}.  @var{bus} is
 either the keyword @code{:system} or the keyword @code{:session}.
@@ -1245,6 +1245,11 @@ running):
 @result{} "/org/freedesktop/systemd1/job/17508"
 @end lisp
 
+If the parameter @code{:keep-fd} is given, and the return message has a
+first argument with a D-Bus type @code{:unix-fd}, the returned file
+descriptor is kept internally, and can be used in a later call of
+@code{dbus--close-fd} (@pxref{File Descriptors}).
+
 The remaining arguments @var{args} are passed to @var{method} as
 arguments.  They are converted into D-Bus types as described in
 @ref{Type Conversion}.
@@ -1324,7 +1329,7 @@ emulate the @code{lshal} command on GNU/Linux systems:
 @cindex method calls, asynchronous
 @cindex asynchronous method calls
 
-@defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout :authorizable auth &rest args
+@defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout :authorizable auth :keep-fd &rest args
 This function calls @var{method} on the D-Bus @var{bus}
 asynchronously.  @var{bus} is either the keyword @code{:system} or the
 keyword @code{:session}.
@@ -1347,6 +1352,11 @@ If the parameter @code{:authorizable} is given and the following
 @var{auth} is non-@code{nil}, the invoked method may interactively
 prompt the user for authorization.  The default is @code{nil}.
 
+If the parameter @code{:keep-fd} is given, and the return message has a
+first argument with a D-Bus type @code{:unix-fd}, the returned file
+descriptor is kept internally, and can be used in a later call of
+@code{dbus--close-fd} (@pxref{File Descriptors}).
+
 The remaining arguments @var{args} are passed to @var{method} as
 arguments.  They are converted into D-Bus types as described in
 @ref{Type Conversion}.
@@ -2205,109 +2215,90 @@ switches to the monitor buffer.
 @end deffn
 
 
-@node Inhibitor Locks
-@chapter Inhibit system shutdowns and sleep states
-
-@uref{https://systemd.io/INHIBITOR_LOCKS/, Systemd} includes a logic to
-inhibit system shutdowns and sleep states.  It can be controlled by a
-D-Bus API@footnote{@uref{https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.login1.html}}.
-Because this API includes handling of file descriptors, not all
-functions can be implemented by simple D-Bus method calls.  Therefore,
-the following functions are provided.
-
-@defun dbus-make-inhibitor-lock what why &optional block
-This function creates an inhibitor for system shutdowns and sleep states.
-
-@var{what} is a colon-separated string of lock types: @samp{shutdown},
-@samp{sleep}, @samp{idle}, @samp{handle-power-key},
-@samp{handle-suspend-key}, @samp{handle-hibernate-key},
-@samp{handle-lid-switch}. Example: @samp{shutdown:idle}.
-
-@c@var{who} is a descriptive string of who is taking the lock.  If it is
-@c@code{nil}, it defaults to @samp{Emacs}.
+@node File Descriptors
+@chapter Handle file descriptors
 
-@var{why} is a descriptive string of why the lock is taken. Example:
-@samp{Package Update in Progress}.
+Methods offered by the D-Bus API could return a file descriptor, which
+must be handled further.  This is indicated by the @code{:keep-fd}
+parameter when calling the method (@pxref{dbus-call-method}).
 
-The optional @var{block} is the mode of the inhibitor lock, either
-@samp{block} (@var{block} is non-@code{nil}), or @samp{delay}.
-
-Note, that the @code{who} argument of the inhibitor lock object of the
-systemd manager is always set to the string @samp{Emacs}.
-
-It returns a file descriptor or @code{nil}, if the lock cannot be
-acquired.  If there is already an inhibitor lock for the triple
-@code{(WHAT WHY BLOCK)}, this lock is returned.  Example:
+For example, @uref{https://systemd.io/INHIBITOR_LOCKS/, Systemd}
+includes a logic to inhibit system shutdowns and sleep states.  It can
+be controlled by a the method @samp{Inhibit} of interface
+@samp{org.freedesktop.login1.Manager}@footnote{@uref{https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.login1.html}}.
+This function returns a file descriptor, which must be used to unlock
+the locked resource, some of which lock the system.  In order to keep
+this file descriptor internally, the respective D-Bus method call looks
+like (@var{what}, @var{who}, @var{why} and @var{mode} are
+method-specific string arguments)
 
 @lisp
-(dbus-make-inhibitor-lock "sleep" "Test")
+(dbus-call-method
+ :system
+ "org.freedesktop.login1" "/org/freedesktop/login1"
+ "org.freedesktop.login1.Manager" "Inhibit"
+ :keep-fd WHAT WHO WHY MODE)
 
 @result{} 25
 @end lisp
-@end defun
 
-@defun dbus-registered-inhibitor-locks
-Return registered inhibitor locks, an alist.
-This allows to check, whether other packages of the running Emacs
-instance have acquired an inhibitor lock as well.
+The inhibition lock is unlocked, when the returned file descriptor is
+removed from the file system.  This cannot be achieved on Lisp level.
+Therefore, there is the function @code{dbus--fd-close} to performs this
+task (see below).
+
+@strong{Note}: When the Emacs process itself dies, all such locks are
+released.
 
-An entry in this list is a list @code{(@var{fd} @var{what} @var{why}
-@var{block})}.  The car of the list is the file descriptor retrieved
-from a @code{dbus-make-inhibitor-lock} call.  The cdr of the list
-represents the three arguments @code{dbus-make-inhibitor-lock} was
-called with.  Example:
+@strong{Note}: The following functions are internal to the D-Bus
+implementation of Emacs.  Use them with care.
+
+@defun dbus--fd-open filename
+Open @var{filename} and return the respective read-only file descriptor.
+This is another function to keep a file descriptor internally.  The
+returned file descriptor can be closed by @code{dbus--fd-close}.
+Example:
 
 @lisp
-(dbus-registered-inhibitor-locks)
+(dbus--fd-open "~/.emacs")
 
-@result{} ((25 "sleep" "Test" nil))
+@result{} 20
 @end lisp
 @end defun
 
-@defun dbus-close-inhibitor-lock lock
-Close inhibitor lock file descriptor.
-
-@var{lock}, a file descriptor, must be the result of a
-@code{dbus-make-inhibitor-lock} call.  It returns @code{t} in case of
-success, or @code{nil} if it isn't be possible to close the lock, or if
-the lock is closed already.  Example:
+@defun dbus--fd-close fd
+Close file descriptor @var{fd}.
+@var{fd} must be the result of a @code{dbus-call-method} or
+@code{dbus--fd-open} call, see @code{dbus--registered-fds}.  It returns
+@code{t} in case of success, or @code{nil} if it isn’t be possible to
+close the file descriptor, or if the file descriptor is closed already.
+Example:
 
 @lisp
-(dbus-close-inhibitor-lock 25)
+(dbus--fd-close 25)
 
 @result{} t
-
 @end lisp
 @end defun
 
-A typical scenario for these functions is to register for the
-D-Bus signal @samp{org.freedesktop.login1.Manager.PrepareForSleep}:
+@defun dbus--registered-fds
+Return registered file descriptors, an alist.
+The key is an open file descriptor, retrieved via
+@code{dbus-call-method} or @code{dbus--open-fd}.  The value is a string
+@var{object-path} or @var{filename}, which represents the arguments the
+function was called with.  Those values are not needed for further
+operations; they are just shown for information.
 
-@lisp
-(defvar my-inhibitor-lock
-        (dbus-make-inhibitor-lock "sleep" "Test"))
+This alist allows to check, whether other packages of the running Emacs
+instance have acquired a file descriptor as well.  Example:
 
-(defun my-dbus-PrepareForSleep-handler (start)
-  (if start ;; The system goes down for sleep
-      (progn
-        @dots{}
-        ;; Release inhibitor lock.
-        (when (natnump my-inhibitor-lock)
-          (dbus-close-inhibitor-lock my-inhibitor-lock)
-          (setq my-inhibitor-lock nil)))
-    ;; Reacquire inhibitor lock.
-    (setq my-inhibitor-lock
-          (dbus-make-inhibitor-lock "sleep" "Test"))))
-
-(dbus-register-signal
- :system "org.freedesktop.login1" "/org/freedesktop/login1"
- "org.freedesktop.login1.Manager" "PrepareForSleep"
- #'my-dbus-PrepareForSleep-handler)
+@lisp
+(dbus--registered-fds)
 
-@result{} ((:signal :system "org.freedesktop.login1.Manager" "PrepareForSleep")
-    ("org.freedesktop.login1" "/org/freedesktop/login1"
-      my-dbus-PrepareForSleep-handler))
+@result{} ((20 . "/home/user/.emacs")
+   (25 . "/org/freedesktop/login1"))
 @end lisp
+@end defun
 
 
 @node Index
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index c916588a060..73c3e1ed326 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -6658,7 +6658,7 @@ root directory, it is most likely sufficient to make the
 @code{default-directory} of the process buffer as the root directory.
 
 
-@subsection Timers, process filters, process sentinels, redisplay
+@subsection Timers, process filters, process sentinels, special events, redisplay
 
 @vindex remote-file-error
 Timers run asynchronously at any time when Emacs is waiting for
@@ -6678,7 +6678,13 @@ wrapping the timer function body as follows:
 @end lisp
 
 A similar problem could happen with process filters, process
-sentinels, and redisplay (updating the mode line).
+sentinels, special event handlers, and redisplay (updating the mode
+line).
+
+@strong{Note} that @value{tramp} raises a @code{remote-file-error}
+error for any connection-related problem.  You can protect against all
+such problems with the code snippet above (or with a
+@code{condition-case} form with a @code{remote-file-error} handler).
 
 
 @node Extension packages
diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi
index 1cdeab5bbaa..b7ce3f7a262 100644
--- a/doc/misc/widget.texi
+++ b/doc/misc/widget.texi
@@ -785,13 +785,19 @@ The following navigation commands are available:
 
 @table @kbd
 @item @key{TAB}
-@deffn Command widget-forward &optional count
-Move point @var{count} buttons or editing fields forward.
+@deffn Command widget-forward count &optional suppress-echo
+Move point @var{count} buttons or editing fields forward.  The optional
+@var{suppress-echo} argument suppresses showing in the echo-area the
+help-echo text, if any, for the final position after the move; it is
+always @code{nil} in interactive invocations.
 @end deffn
 @item M-@key{TAB}
 @itemx S-@key{TAB}
-@deffn Command widget-backward &optional count
-Move point @var{count} buttons or editing fields backward.
+@deffn Command widget-backward count &optional suppress-echo
+Move point @var{count} buttons or editing fields backward.  The optional
+@var{suppress-echo} argument suppresses showing in the echo-area the
+help-echo text, if any, for the final position after the move; it is
+always @code{nil} in interactive invocations.
 @end deffn
 @end table