9 files changed, 173 insertions, 34 deletions

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